codex-pdf 1.7.0__tar.gz → 1.7.2__tar.gz

{codex_pdf-1.7.0 → codex_pdf-1.7.2}/CLAUDE.md

@@ -25,7 +25,7 @@ For new products (Forge, Trap, Impose, Marks, etc.), map capabilities to one own
 
 When work spans layers, define a contract seam and keep logic in its owner service.
 
-## Deployed surface (1.7.0)
+## Deployed surface (1.7.2)
 
 Codex now runs as **three services** in production. They share the
 same content-addressed cache key format

codex_pdf-1.7.2/CONTRIBUTING.md

@@ -0,0 +1,84 @@
+# Contributing to codex-pdf
+
+`codex-pdf` is the read-only PDF facts + render service for the
+Print with Synergy / Think Neverland tool family. It owns
+extraction, normalization, and reusable summary payloads — keeping
+outputs deterministic, versioned, and backward-compatible.
+
+Before opening a PR, please confirm your change fits codex's lane
+(extraction / normalized facts / detection signals) rather than a
+display or rules concern. UI presentation belongs to **Loupe** and
+rule pass/fail logic belongs to **Lint** — see
+[`docs/service-ownership-contract.md`](./docs/service-ownership-contract.md).
+
+## Local setup
+
+```bash
+git clone https://github.com/printwithsynergy/codex-pdf
+cd codex-pdf
+uv sync
+```
+
+## Running the test suite
+
+The full sweep, including the producer-surface audit that gates the
+read-only invariant:
+
+```bash
+uv run pytest -q
+uv run python scripts/produce_surface_audit.py
+```
+
+TypeScript client + Cloudflare Worker:
+
+```bash
+cd clients/ts && npm test
+cd ../../codex-edge && npx tsc --noEmit && npx vitest run
+```
+
+## Conventions
+
+- **Schema additions are additive.** Adding a field is a minor bump
+  (`MINOR` of `codex_pdf.version.VERSION` and the relevant
+  `*_SCHEMA_VERSION`). Changing a field's shape or removing a field
+  is a major bump and must be paired with consumer migrations in
+  `lint-pdf` / `loupe-pdf` before the codex release ships.
+- **Read-only.** Codex never produces new PDF bytes. The audit at
+  `scripts/produce_surface_audit.py` enforces this; it must stay
+  green on every commit.
+- **No customer policy.** Detection signals belong here; pass/fail
+  verdicts belong in Lint.
+- **Branches** are named `claude/<short-topic>-<version>` for agent
+  work; humans use whatever they like.
+- **Commits** follow Conventional Commits (`feat:`, `fix:`, `chore:`,
+  `perf:`, `docs:`).
+
+## Releasing a new VERSION
+
+When bumping `codex_pdf.version.VERSION`:
+
+1. Update `pyproject.toml`, `src/codex_pdf/version.py`,
+   `clients/ts/package.json`, `codex-edge/wrangler.toml`
+   (`CODEX_VERSION`), and the deployed-surface heading in
+   [`CLAUDE.md`](./CLAUDE.md).
+2. `uv build` → publish wheel + sdist to PyPI.
+3. `npm publish --access public` from `clients/ts`.
+4. `wrangler deploy` from `codex-edge` so KV cache keys rotate.
+5. Railway autodeploys the API + speculator from `main`.
+
+Cache keys (`codex:{VERSION}:{kind}:{pdf_sha}:{args_sha}`) rotate
+atomically across all three tiers when `VERSION` changes — no KV
+purge needed.
+
+## Reporting bugs
+
+Please open a GitHub issue with:
+
+- A minimal reproducing PDF (or its `pdf_sha256` and how it was
+  generated) when the bug is content-dependent.
+- The `codex-pdf --version` (or the `version` field returned by
+  `GET /v1/version`).
+- The exact request / CLI invocation.
+
+For security issues, see [`SECURITY.md`](./SECURITY.md) — please do
+**not** open a public issue.

codex_pdf-1.7.2/PKG-INFO

@@ -0,0 +1,134 @@
+Metadata-Version: 2.4
+Name: codex-pdf
+Version: 1.7.2
+Summary: Authoritative, versioned PDF facts contract for Think Neverland tools.
+Author-email: Think Neverland <dev@thinkneverland.com>
+License-Expression: AGPL-3.0-or-later
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: fastapi>=0.115
+Requires-Dist: gunicorn>=23.0
+Requires-Dist: jsonschema>=4.23
+Requires-Dist: pikepdf>=9.0
+Requires-Dist: pydantic>=2.8
+Requires-Dist: pymupdf>=1.24
+Requires-Dist: python-multipart>=0.0.9
+Requires-Dist: structlog>=24.1
+Requires-Dist: uvicorn>=0.30
+Provides-Extra: geom
+Requires-Dist: pyclipr>=0.1.8; extra == 'geom'
+Provides-Extra: redis
+Requires-Dist: redis>=5.0; extra == 'redis'
+Description-Content-Type: text/markdown
+
+---
+title: "Overview"
+description: "Authoritative read-only PDF facts + render engine for Print with Synergy / Think Neverland tools. Versioned contract, schema-validated output, deployed as three services."
+group: "Getting started"
+order: 1
+slug: "overview"
+---
+
+# codexPDF
+
+`codexPDF` is the authoritative, read-only PDF facts + render reference
+for the Print with Synergy / Think Neverland tool family.
+
+Other engines consult `codexPDF` for canonical document facts instead
+of re-parsing PDFs independently. The contract is versioned and
+schema-validated.
+
+## Status
+
+`codex-pdf 1.7.0`. Current surface includes:
+
+- Python package (`codex_pdf`) with typed `pydantic` models.
+- CLI (`codex-pdf extract|schema|contract|validate|probe|parity|render|serve`).
+- HTTP API (`/v1/extract`, `/v1/probe`, `/v1/extract/stream`,
+  `/v1/render/{page,separations,heatmap,layer}`,
+  `/v1/sample/{color,density}`, `/v1/walk/{type4,content-stream}`,
+  `/v1/color/{resolve,match-pantone,inkbook}`,
+  `/v1/geom/{tile,intersect,union,difference}`).
+- TypeScript client (`@printwithsynergy/codex-client`) mirroring the
+  Python `codex_pdf.client` surface, with SSE streaming for probe
+  and extract.
+- Versioned schemas in `schemas/v1/` (document, color, geom).
+- Cloudflare Worker (`codex-edge`) providing a KV-backed
+  write-through cache layer in front of the API.
+- Redis-Streams speculator (`codex-speculator`) that pre-warms
+  Phase 1 + Phase 2 caches.
+
+See [`CLAUDE.md`](./CLAUDE.md) for the full deployed-service map
+(URLs, account IDs, version-bump checklist).
+
+## Quickstart
+
+```bash
+uv sync
+uv run codex-pdf probe input.pdf --json
+uv run codex-pdf extract input.pdf --pretty > out.json
+uv run codex-pdf validate out.json
+uv run codex-pdf parity --fixtures-root tests/fixtures --profile summary --max-files 5
+```
+
+Run the HTTP API locally:
+
+```bash
+uv run codex-pdf serve --host 0.0.0.0 --port 8080
+curl localhost:8080/v1/version
+```
+
+## Contract
+
+The public surface is the JSON contract rooted at `CodexDocument`,
+plus the per-section contracts under color and geom.
+
+- Document schema: `schemas/v1/codex-document.schema.json`
+- Runtime model: `codex_pdf.models.v1.CodexDocument`
+- Stability policy: SemVer (`major` for breaking contract changes;
+  field additions are minor bumps).
+- Live contract endpoint: `GET /v1/contract` returns the endpoint
+  inventory plus `section_schema_versions`.
+
+## Documentation
+
+| Topic | Doc |
+| --- | --- |
+| Architecture and boundaries | [docs/architecture.md](./docs/architecture.md) |
+| CLI commands and usage | [docs/cli.md](./docs/cli.md) |
+| Contract and schema versioning | [docs/contract.md](./docs/contract.md) |
+| Deploying the API + speculator + edge | [docs/deploy.md](./docs/deploy.md) |
+| Parity profiles and baselines | [docs/parity.md](./docs/parity.md) |
+| Preflight ingest adapters | [docs/preflight-ingest.md](./docs/preflight-ingest.md) |
+| Service-ownership contract | [docs/service-ownership-contract.md](./docs/service-ownership-contract.md) |
+| Codex change ripple rule | [docs/operations/codex-change-ripple.md](./docs/operations/codex-change-ripple.md) |
+| Marketing deploy template | [docs/operations/marketing-deploy-template.md](./docs/operations/marketing-deploy-template.md) |
+
+## Contributing
+
+We welcome PRs that fit codex's lane (extraction, normalization,
+detection signals). Display concerns belong in **Loupe**; rule
+pass/fail logic belongs in **Lint**.
+
+Read [`CONTRIBUTING.md`](./CONTRIBUTING.md) for the dev setup, test
+commands, schema-bump rules, and release checklist.
+
+## Security
+
+Please report vulnerabilities privately to
+**`security@thinkneverland.com`** — do not open a public issue.
+
+The full disclosure policy, supported-version matrix, and scope
+(including the read-only PDF invariant) live in
+[`SECURITY.md`](./SECURITY.md).
+
+## License
+
+`codexPDF` is distributed under the **GNU Affero General Public
+License v3.0 or later** (`SPDX-License-Identifier:
+AGPL-3.0-or-later`). The full license text is in
+[`LICENSE`](./LICENSE).
+
+AGPL applies in particular when codex is reachable over a network —
+modifications served to remote users must be made available to
+those users under the same terms.

codex_pdf-1.7.2/README.md

@@ -0,0 +1,111 @@
+---
+title: "Overview"
+description: "Authoritative read-only PDF facts + render engine for Print with Synergy / Think Neverland tools. Versioned contract, schema-validated output, deployed as three services."
+group: "Getting started"
+order: 1
+slug: "overview"
+---
+
+# codexPDF
+
+`codexPDF` is the authoritative, read-only PDF facts + render reference
+for the Print with Synergy / Think Neverland tool family.
+
+Other engines consult `codexPDF` for canonical document facts instead
+of re-parsing PDFs independently. The contract is versioned and
+schema-validated.
+
+## Status
+
+`codex-pdf 1.7.0`. Current surface includes:
+
+- Python package (`codex_pdf`) with typed `pydantic` models.
+- CLI (`codex-pdf extract|schema|contract|validate|probe|parity|render|serve`).
+- HTTP API (`/v1/extract`, `/v1/probe`, `/v1/extract/stream`,
+  `/v1/render/{page,separations,heatmap,layer}`,
+  `/v1/sample/{color,density}`, `/v1/walk/{type4,content-stream}`,
+  `/v1/color/{resolve,match-pantone,inkbook}`,
+  `/v1/geom/{tile,intersect,union,difference}`).
+- TypeScript client (`@printwithsynergy/codex-client`) mirroring the
+  Python `codex_pdf.client` surface, with SSE streaming for probe
+  and extract.
+- Versioned schemas in `schemas/v1/` (document, color, geom).
+- Cloudflare Worker (`codex-edge`) providing a KV-backed
+  write-through cache layer in front of the API.
+- Redis-Streams speculator (`codex-speculator`) that pre-warms
+  Phase 1 + Phase 2 caches.
+
+See [`CLAUDE.md`](./CLAUDE.md) for the full deployed-service map
+(URLs, account IDs, version-bump checklist).
+
+## Quickstart
+
+```bash
+uv sync
+uv run codex-pdf probe input.pdf --json
+uv run codex-pdf extract input.pdf --pretty > out.json
+uv run codex-pdf validate out.json
+uv run codex-pdf parity --fixtures-root tests/fixtures --profile summary --max-files 5
+```
+
+Run the HTTP API locally:
+
+```bash
+uv run codex-pdf serve --host 0.0.0.0 --port 8080
+curl localhost:8080/v1/version
+```
+
+## Contract
+
+The public surface is the JSON contract rooted at `CodexDocument`,
+plus the per-section contracts under color and geom.
+
+- Document schema: `schemas/v1/codex-document.schema.json`
+- Runtime model: `codex_pdf.models.v1.CodexDocument`
+- Stability policy: SemVer (`major` for breaking contract changes;
+  field additions are minor bumps).
+- Live contract endpoint: `GET /v1/contract` returns the endpoint
+  inventory plus `section_schema_versions`.
+
+## Documentation
+
+| Topic | Doc |
+| --- | --- |
+| Architecture and boundaries | [docs/architecture.md](./docs/architecture.md) |
+| CLI commands and usage | [docs/cli.md](./docs/cli.md) |
+| Contract and schema versioning | [docs/contract.md](./docs/contract.md) |
+| Deploying the API + speculator + edge | [docs/deploy.md](./docs/deploy.md) |
+| Parity profiles and baselines | [docs/parity.md](./docs/parity.md) |
+| Preflight ingest adapters | [docs/preflight-ingest.md](./docs/preflight-ingest.md) |
+| Service-ownership contract | [docs/service-ownership-contract.md](./docs/service-ownership-contract.md) |
+| Codex change ripple rule | [docs/operations/codex-change-ripple.md](./docs/operations/codex-change-ripple.md) |
+| Marketing deploy template | [docs/operations/marketing-deploy-template.md](./docs/operations/marketing-deploy-template.md) |
+
+## Contributing
+
+We welcome PRs that fit codex's lane (extraction, normalization,
+detection signals). Display concerns belong in **Loupe**; rule
+pass/fail logic belongs in **Lint**.
+
+Read [`CONTRIBUTING.md`](./CONTRIBUTING.md) for the dev setup, test
+commands, schema-bump rules, and release checklist.
+
+## Security
+
+Please report vulnerabilities privately to
+**`security@thinkneverland.com`** — do not open a public issue.
+
+The full disclosure policy, supported-version matrix, and scope
+(including the read-only PDF invariant) live in
+[`SECURITY.md`](./SECURITY.md).
+
+## License
+
+`codexPDF` is distributed under the **GNU Affero General Public
+License v3.0 or later** (`SPDX-License-Identifier:
+AGPL-3.0-or-later`). The full license text is in
+[`LICENSE`](./LICENSE).
+
+AGPL applies in particular when codex is reachable over a network —
+modifications served to remote users must be made available to
+those users under the same terms.

codex_pdf-1.7.2/SECURITY.md

@@ -0,0 +1,72 @@
+# Security policy
+
+`codex-pdf` parses untrusted PDF input on behalf of upstream services
+(Loupe, Lint, marketing demos). We take vulnerability reports
+seriously — especially around PDF parsing, SSRF, authentication, and
+cache-poisoning vectors.
+
+## Reporting a vulnerability
+
+Please **do not open a public GitHub issue**.
+
+Email security disclosures to **`security@thinkneverland.com`**.
+If you need an encrypted channel, request our PGP key in the first
+message and we will reply with the fingerprint and public key.
+
+A useful report includes:
+
+- The codex-pdf version (`GET /v1/version` or the published package
+  version on PyPI / npm).
+- Whether the issue is reachable through the deployed Railway API,
+  the codex-edge Cloudflare Worker, the local CLI, the Python or
+  TypeScript SDK — or some combination.
+- A minimal reproducer: a PDF / JSON request body / curl invocation
+  that triggers the issue.
+- The behaviour observed and the behaviour you expected.
+
+## Response timeline
+
+- We acknowledge receipt within **two business days**.
+- We aim to ship a fix or mitigation within **30 days** for
+  high-severity issues, **90 days** for low-severity.
+- You will be credited in the release notes (and the security
+  advisory, when one is published) unless you ask to remain
+  anonymous.
+
+## Supported versions
+
+Only the latest minor release is patched for security issues. Older
+minors get advisories but no backports.
+
+| Version | Status |
+|---------|--------|
+| `1.7.x` | ✅ patched |
+| `< 1.7` | ❌ unsupported — please upgrade |
+
+## In scope
+
+- The Python package (`pip install codex-pdf`) and its CLI.
+- The TypeScript client (`@printwithsynergy/codex-client`).
+- The deployed Railway HTTP API
+  (`codex-pdf-lint-sidecar-production.up.railway.app`).
+- The Cloudflare Worker (`codex-edge.thinkneverland.workers.dev`).
+- The codex-speculator Redis-Streams consumer.
+
+## Out of scope
+
+- Issues in upstream dependencies (PyMuPDF, pikepdf, Ghostscript)
+  that have already been disclosed upstream — please report those
+  to the upstream project.
+- Denial-of-service from PDFs that legitimately take a long time to
+  parse but are not malformed (for example, very large multi-page
+  artwork). Codex sets a hard timeout; reports about *bypassing*
+  that timeout are in scope.
+- Self-inflicted misconfiguration (e.g. running with no auth tokens
+  set on a public network).
+
+## Scope of the read-only invariant
+
+Codex never produces new PDF bytes. If you can demonstrate codex
+emitting a PDF or a `b"%PDF-"` payload through any of the surfaces
+above, that is a security finding even if no other compromise
+follows — please report it.

{codex_pdf-1.7.0 → codex_pdf-1.7.2}/clients/ts/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@printwithsynergy/codex-client",
-  "version": "1.7.0",
+  "version": "1.7.2",
   "description": "TypeScript client for the codex-pdf HTTP API. Mirrors the Python codex_pdf.client surface.",
   "type": "module",
   "license": "AGPL-3.0-or-later",

{codex_pdf-1.7.0 → codex_pdf-1.7.2}/codex-edge/README.md

@@ -10,7 +10,7 @@ the Railway codex-pdf service.
 - **Account**: `99aa3f9229469650a746a7d39ac58448` (`Quincy@thinkneverland.com's Account`)
 - **KV namespace `CACHE`**: `89a21ce1937046018a3d9d38f4e763ff` (preview `a4856d6f3b244087b907c189c2a2277d`)
 - **Origin** (`CODEX_ORIGIN_URL`): `https://codex-pdf-lint-sidecar-production.up.railway.app`
-- **Codex version pinned**: `1.7.0` (`CODEX_VERSION` var — bump on origin release)
+- **Codex version pinned**: `1.7.2` (`CODEX_VERSION` var — bump on origin release)
 - **TTLs**: probe 24 h, Phase 1 24 h, Phase 2 7 d
 
 ## What it caches

{codex_pdf-1.7.0 → codex_pdf-1.7.2}/codex-edge/wrangler.toml

@@ -23,7 +23,7 @@ CODEX_ORIGIN_URL = "https://codex-pdf-lint-sidecar-production.up.railway.app"
 # Codex package VERSION at deploy time. MUST match the origin's
 # `codex_pdf.version.VERSION` so KV keys line up. Bump on every
 # origin release.
-CODEX_VERSION = "1.7.0"
+CODEX_VERSION = "1.7.2"
 # TTL (seconds) for cached SSE event payloads.
 PROBE_TTL = "86400"     # 24 h — small payload, refresh daily
 PHASE1_TTL = "86400"    # 24 h — matches origin Redis TTL

codex_pdf-1.7.2/docs/architecture.md

@@ -0,0 +1,79 @@
+---
+title: "Architecture"
+description: "codexPDF boundaries, extraction + render pipeline, and the three deployed services that share one cache key namespace."
+group: "Getting started"
+order: 2
+---
+
+# Architecture
+
+`codexPDF` is a contract-first facts engine for PDF documents.
+
+## Boundary
+
+- Read-only extraction + render. Codex never produces new PDF bytes
+  — `scripts/produce_surface_audit.py` enforces this on every CI
+  run.
+- No customer policy / rule adjudication. Codex emits detection
+  signals; pass/fail belongs to **Lint**.
+- No display / viewer presentation. PNG renders are byte-accurate
+  source-of-truth for **Loupe** to display, not a viewer in
+  themselves.
+- Consumer-agnostic output: same JSON contract regardless of
+  caller.
+
+## Pipeline
+
+1. Input PDF bytes are loaded by the extractor layer (PyMuPDF
+   for the fast path, pikepdf for slower per-object inspection).
+2. Domain extractors populate `CodexDocument` fields: pages,
+   boxes, fonts, images, color spaces (with Separation tint
+   transforms evaluated at `t=1.0` so spot inks land on the right
+   swatch), OCG / layers, annotations, transparency, trapping,
+   form XObjects.
+3. Output is serialized as JSON against the published schemas in
+   `schemas/v1/`. Each section (document, color, geom) versions
+   independently and reports its `schema_version` inline.
+4. Render endpoints rasterize pages, separations, TAC heatmaps,
+   and OCG-isolated layers via Ghostscript + PyMuPDF.
+
+## Primary contract
+
+- Runtime model: `codex_pdf.models.v1.CodexDocument`
+- Document schema: `schemas/v1/codex-document.schema.json`
+- Section versions: `codex_pdf.color.COLOR_SCHEMA_VERSION`,
+  `codex_pdf.geom.GEOM_SCHEMA_VERSION`
+- Live manifest: `GET /v1/contract`
+
+## Deployed surface
+
+In production, codex runs as **three services** sharing one
+content-addressed cache namespace
+(`codex:{VERSION}:{kind}:{pdf_sha}:{args_sha}`), so a `VERSION`
+bump invalidates every tier atomically. The full deployed map —
+URLs, account / service IDs, and the version-bump checklist —
+lives in [`CLAUDE.md`](../CLAUDE.md).
+
+1. **codex-pdf API** (Railway) — FastAPI under gunicorn + uvicorn
+   workers. Bearer + internal token auth. Backed by Redis for
+   cache and blob storage.
+2. **codex-speculator** (Railway sidecar) — a Redis-Streams
+   consumer. `POST /v1/probe` and the blob-store put both XADD a
+   sha onto the `codex:speculate` stream; the speculator runs
+   Phase 1 + Phase 2 ahead of the next request so `/v1/extract`
+   lands warm. Idempotent — cache-hit short-circuit collapses
+   replays to a single Redis GET.
+3. **codex-edge** (Cloudflare Worker + KV) — drop-in DNS-level
+   replacement that captures every probe / extract SSE frame and
+   replays from KV on the next hash-keyed request. Multipart
+   uploads bypass to origin. `ctx.waitUntil` keeps the Worker
+   alive long enough to persist every frame before the response
+   stream closes.
+
+## Consumer relationship
+
+Downstream engines (`lint-pdf`, `loupe-pdf`, marketing demos)
+treat codex output as the source of truth for document facts and
+keep any product-specific behaviour in adapter layers. New
+products map to one owner per capability — see
+[`docs/service-ownership-contract.md`](./service-ownership-contract.md).

codex_pdf-1.7.2/docs/cli.md

@@ -0,0 +1,91 @@
+---
+title: "CLI"
+description: "Command reference for extract, probe, render, serve, parity, schema, contract, and validate workflows."
+group: "Getting started"
+order: 3
+---
+
+# CLI
+
+`codex-pdf` exposes a contract-oriented CLI built with `argparse`.
+The same code path that the HTTP API uses runs in-process when you
+invoke the CLI, so output is byte-for-byte identical to the
+deployed surface.
+
+## Commands
+
+| Command | Purpose |
+|---|---|
+| `extract <pdf>` | Emit the full `CodexDocument` JSON. |
+| `probe <pdf>` | Two-event metadata probe (page count, dimensions, info dict, `pdf_sha256`). |
+| `schema [name]` | Print a published JSON schema (default: `codex-document`). |
+| `contract` | Print the machine-readable contract manifest (endpoint inventory + section schema versions). |
+| `validate <codex_json>` | Validate a codex JSON payload against the published schema. |
+| `parity` | Compare codex projections against a baseline command. |
+| `render page` | Render one page to PNG. |
+| `render separations` | Render every separation channel for one page. |
+| `render heatmap` | Render a TAC heatmap PNG plus a per-run header. |
+| `render layer` | Render one OCG-isolated layer to RGBA PNG. |
+| `serve` | Start the codex HTTP API (uvicorn, in-process). |
+
+## Common usage
+
+```bash
+uv run codex-pdf extract input.pdf --pretty > out.json
+uv run codex-pdf validate out.json
+uv run codex-pdf probe input.pdf --json
+uv run codex-pdf contract --pretty
+```
+
+## Streaming probe / extract (HTTP only)
+
+The CLI's `probe` and `extract` are synchronous. The deployed HTTP
+API also exposes streaming variants that emit Phase 1 results as
+soon as PyMuPDF is finished and Phase 2 once pikepdf adds the
+slower fields:
+
+- `POST /v1/probe` — server-sent events with two frames (`probe-min`
+  immediately, `probe-std` after the secondary parse).
+- `POST /v1/extract/stream` — same shape for full extraction; pass
+  `?granular=1` to get per-section progress events.
+
+The TypeScript client's `probeStream()` and `extractStream()` wrap
+this directly; the Python `codex_pdf.client.HttpClient` also has
+streaming helpers when used against a remote API.
+
+## Render usage
+
+```bash
+uv run codex-pdf render page input.pdf --page 0 --dpi 144 -o page.png
+uv run codex-pdf render separations input.pdf --page 0 -o seps/
+uv run codex-pdf render heatmap input.pdf --page 0 -o tac.png
+uv run codex-pdf render layer input.pdf --page 0 --ocg "Dieline" -o dieline.png
+```
+
+## Parity usage
+
+```bash
+uv run codex-pdf parity \
+  --fixtures-root tests/fixtures \
+  --profile deep \
+  --max-files 10
+```
+
+Baseline command mode:
+
+```bash
+uv run codex-pdf parity \
+  --fixtures-root /path/to/pdfs \
+  --profile summary \
+  --baseline-command "<command with {pdf} placeholder>"
+```
+
+## Local server
+
+```bash
+uv run codex-pdf serve --host 0.0.0.0 --port 8080
+curl localhost:8080/v1/version
+```
+
+The same image, in production, runs under gunicorn + uvicorn workers
+via the Dockerfile's `CMD` — see [`docs/deploy.md`](./deploy.md).

{codex_pdf-1.7.0 → codex_pdf-1.7.2}/docs/contract.md

@@ -20,7 +20,9 @@ mode for examples.
 | `GET /v1/version` | meta | render | bare `{version}` |
 | `GET /v1/contract` | meta | render | endpoint inventory + `section_schema_versions` |
 | `GET /v1/schema/{name}` | document | extract | JSON schemas served from `schemas/v1/<name>.schema.json` |
-| `POST /v1/extract`, `POST /extract` | document | extract | multipart PDF or JSON `{url}` → CodexDocument |
+| `POST /v1/extract`, `POST /extract` | document | extract | multipart PDF or JSON `{url, pdf_sha256}` → CodexDocument |
+| `POST /v1/probe` | document | extract | two-event SSE stream: `probe-min` (instant) + `probe-std` (after secondary parse) |
+| `POST /v1/extract/stream` | document | extract | SSE stream of `phase-1` + `phase-2` extract events; `?granular=1` adds per-section progress |
 | `POST /v1/render/page` | document | render | PNG raster |
 | `POST /v1/render/separations` | document | render | tiffsep channel manifest |
 | `POST /v1/render/heatmap` | document | render | TAC heatmap PNG + per-run header |
@@ -56,10 +58,10 @@ Sample contract response:
 ```json
 {
   "contract_name": "codex-document",
-  "schema_version": "1.0.0",
-  "package_version": "1.4.0",
+  "schema_version": "1.1.0",
+  "package_version": "1.7.0",
   "schema_id": "https://schemas.thinkneverland.com/codex-pdf/v1/codex-document.schema.json",
-  "endpoints": ["POST /v1/extract", "..."],
+  "endpoints": ["POST /v1/extract", "POST /v1/probe", "POST /v1/extract/stream", "..."],
   "section_schema_versions": {
     "color": "1.0.0",
     "geom": "1.0.0"
@@ -104,6 +106,4 @@ status changes commit-by-commit.
 
 Any future need to write PDF bytes goes into a separate Forge
 service (rewrite, marks, impose, trap), never into a consumer.
-Codex stays read-only; consumers stay byte-level-clean. Refer to
-`/Users/macadmin/Code/printwithsynergy/FORGE-DESIGN-PROMPT.md` for
-the next-session Q&A that defines the Forge contract.
+Codex stays read-only; consumers stay byte-level-clean.