codex-pdf 1.4.0__tar.gz → 1.4.2__tar.gz

codex_pdf-1.4.2/.cursor/rules/service-ownership.mdc

@@ -0,0 +1,12 @@
+---
+description: Service ownership boundary for Loupe/Lint/Codex and future offshoots
+alwaysApply: true
+---
+
+# Service Ownership Boundary
+
+- **Codex owns** extraction, normalization, and reusable summary/detection payloads.
+- **Lint owns** policy rules, reporting semantics, and preflight workflow orchestration.
+- **Loupe owns** rendering, visual inspection UI, and display interactions.
+- Keep Codex rule-agnostic; never hardcode customer pass/fail policy in this repo.
+- For offshoots (Forge, Trap, Impose, Marks, etc.), map each feature to one owner layer and integrate by contract, not duplicated logic.

{codex_pdf-1.4.0 → codex_pdf-1.4.2}/.gitignore

@@ -9,3 +9,4 @@ build/
 *.egg-info/
 coverage.xml
 htmlcov/
+node_modules/

codex_pdf-1.4.2/.windsurf/rules/service-ownership.md

@@ -0,0 +1,12 @@
+---
+trigger: always_on
+description: "Service ownership boundary: Codex extraction, Lint rules, Loupe display"
+---
+
+# Service Ownership Boundary
+
+- Codex owns extraction + normalized reusable intelligence payloads.
+- Lint owns reporting/rules/preflight workflow semantics.
+- Loupe owns PDF display and visual inspection UX.
+- Keep this repo policy-agnostic; do not add customer-specific pass/fail rule logic.
+- New offshoots (Forge, Trap, Impose, Marks, etc.) must map capabilities to one owner layer and integrate via contracts.

codex_pdf-1.4.2/CLAUDE.md

@@ -0,0 +1,26 @@
+# Codex PDF — Agent Guidance
+
+## Service boundary
+
+Codex is the extraction and normalized intelligence layer in the Print with Synergy stack.
+
+- Own extraction, normalization, and reusable summary payloads.
+- Keep outputs deterministic, versioned, and backward-compatible.
+- Expose detection signals, not policy verdicts.
+
+## Non-goals for this repo
+
+- Do not implement viewer/UI presentation concerns here.
+- Do not encode customer policy/rule pass-fail logic here.
+
+Those belong to Loupe (display) and Lint (rules/workflow).
+
+## Offshoot rule
+
+For new products (Forge, Trap, Impose, Marks, etc.), map capabilities to one owner:
+
+1. Display/inspection -> Loupe
+2. Rules/reporting/workflow -> Lint
+3. Extraction/normalized facts -> Codex
+
+When work spans layers, define a contract seam and keep logic in its owner service.

{codex_pdf-1.4.0 → codex_pdf-1.4.2}/Dockerfile

@@ -1,8 +1,16 @@
 # Codex shared service image. Single source of truth for shared,
 # per-consumer, and hybrid Railway deployments. The same image runs
 # the FastAPI surface (`POST /v1/extract`, `/v1/render/...`, etc.).
+#
+# Two-stage build:
+#  - `builder` carries gcc / g++ / cmake / ninja so `uv sync` can
+#    compile the optional `[geom]` extra (pyclipr -> Clipper2 C++)
+#    from sdist when no manylinux wheel is available for our arch.
+#  - `base` is the runtime image; only the populated /opt/venv is
+#    copied in, keeping the final image lean (~280 MB) while still
+#    shipping the geom + redis surfaces.
 
-FROM python:3.12-slim AS base
+FROM python:3.12-slim AS builder
 
 ENV PYTHONDONTWRITEBYTECODE=1 \
     PYTHONUNBUFFERED=1 \
@@ -12,7 +20,35 @@ ENV PYTHONDONTWRITEBYTECODE=1 \
     UV_PROJECT_ENVIRONMENT=/opt/venv \
     PATH="/opt/venv/bin:$PATH"
 
-# System packages:
+RUN apt-get update \
+ && apt-get install -y --no-install-recommends \
+        build-essential \
+        cmake \
+        ninja-build \
+        python3-dev \
+        ca-certificates \
+ && rm -rf /var/lib/apt/lists/*
+
+COPY --from=ghcr.io/astral-sh/uv:0.5 /uv /usr/local/bin/uv
+
+WORKDIR /app
+
+COPY pyproject.toml uv.lock README.md ./
+COPY src ./src
+COPY schemas ./schemas
+COPY tests ./tests
+
+RUN uv sync --frozen --no-dev --extra redis --extra geom
+
+
+FROM python:3.12-slim AS base
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    UV_PROJECT_ENVIRONMENT=/opt/venv \
+    PATH="/opt/venv/bin:$PATH"
+
+# Runtime system packages:
 # - ghostscript (>=10) for png16m + tiffsep + simulate-overprint
 # - poppler-utils for pdftoppm/pdftotext fallbacks (TAC heatmap text bboxes)
 # - libheif1 for heif/avif preview ingest paths consumers might rely on
@@ -27,28 +63,20 @@ RUN apt-get update \
         curl \
  && rm -rf /var/lib/apt/lists/*
 
-COPY --from=ghcr.io/astral-sh/uv:0.5 /uv /usr/local/bin/uv
-
 # Non-root user.
 RUN useradd --system --create-home --shell /usr/sbin/nologin codex
 WORKDIR /app
 
+# Copy the pre-built venv from the builder stage and the project
+# sources. Chown to the runtime user so editable installs / module
+# imports don't trip on permission errors at boot.
+COPY --from=builder /opt/venv /opt/venv
 COPY pyproject.toml uv.lock README.md ./
 COPY src ./src
 COPY schemas ./schemas
 COPY tests ./tests
 
-# Build the venv as root so the global cache is shared, then chown
-# everything to the non-root runtime user. Without this, `uv run` at
-# container start tries to repair the editable install and fails on
-# `/opt/venv/.../bin/codex-pdf: Permission denied` because the bin
-# entries land outside the dir tree the runtime user can write.
-# Install the `redis` extra unconditionally so a deploy that wires
-# CODEX_REDIS_URL to a Railway Redis service uses the shared cache,
-# AND a deploy that deletes the redis service still boots cleanly
-# (codex falls back to in-memory; see codex_pdf.api.cache.make_cache).
-RUN uv sync --frozen --no-dev --extra redis \
- && chown -R codex:codex /opt/venv /app
+RUN chown -R codex:codex /opt/venv /app
 
 USER codex
 

{codex_pdf-1.4.0 → codex_pdf-1.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codex-pdf
-Version: 1.4.0
+Version: 1.4.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

codex_pdf-1.4.2/docs/contract.md

@@ -0,0 +1,109 @@
+# codex-pdf contract
+
+`codex-pdf` is the read-only PDF facts + render service for the
+Think Neverland tooling family (lint-pdf, loupe-pdf, the marketing
+demos, and the upcoming Forge producers). This document is the
+canonical pointer for every contract surface codex exposes, the
+versioning policy that governs each section, and the read-only
+invariants the producer-surface audit enforces.
+
+## Contract endpoints (HTTP)
+
+The service mounts at the configured base URL (Railway service
+domain or custom apex). Auth modes are documented in
+[`docs/deploy.md`](./deploy.md); the table below uses the bearer
+mode for examples.
+
+| Endpoint | Section | Owner | Notes |
+|---|---|---|---|
+| `GET /healthz`, `GET /v1/healthz` | meta | render | unauthed liveness; carries `version` and `cache_backend` |
+| `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/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 |
+| `POST /v1/render/layer` | document | render | OCG-toggled layer raster |
+| `POST /v1/sample/color` | document | render | per-pixel sRGB sample |
+| `POST /v1/sample/density` | document | render | per-channel density sample |
+| `POST /v1/walk/content-stream` | document | extract | content-stream signals JSON |
+| `POST /v1/walk/type4` | document | eval | Type-4 PostScript evaluator |
+| `POST /v1/color/resolve` | color | color | host → codex → pantone → curated → hash resolver |
+| `POST /v1/color/match-pantone` | color | color | nearest-Pantone search via ΔE2000 |
+| `GET /v1/color/inkbook` | color | color | curated + Pantone catalogue manifest |
+| `POST /v1/geom/tile` | geom | geom | imposition tile-grid layout |
+| `POST /v1/geom/intersect` | geom | geom | polygon Boolean intersection |
+| `POST /v1/geom/union` | geom | geom | polygon Boolean union |
+| `POST /v1/geom/difference` | geom | geom | polygon Boolean difference |
+| `GET /metrics` | meta | render | Prometheus metrics (when prometheus-client installed) |
+
+## Schema sections + versioning
+
+Each section under codex versions independently of the top-level
+`codex-document` schema. The contract endpoint exposes the per-
+section versions in a single map so SDK consumers can pin against
+exactly the surface they validate.
+
+| Section | Version constant | Current value | Bump policy |
+|---|---|---|---|
+| document (codex-document) | embedded in `/v1/contract.schema_version` | `1.0.0` | additive bumps remain `1.x`; breaking changes go to `2.0.0` |
+| color | `codex_pdf.color.COLOR_SCHEMA_VERSION` | `1.0.0` | bump on any change to `/v1/color/*` request/response shapes |
+| geom | `codex_pdf.geom.GEOM_SCHEMA_VERSION` | `1.0.0` | bump on any change to `/v1/geom/*` request/response shapes |
+
+Sample contract response:
+
+```json
+{
+  "contract_name": "codex-document",
+  "schema_version": "1.0.0",
+  "package_version": "1.4.0",
+  "schema_id": "https://schemas.thinkneverland.com/codex-pdf/v1/codex-document.schema.json",
+  "endpoints": ["POST /v1/extract", "..."],
+  "section_schema_versions": {
+    "color": "1.0.0",
+    "geom": "1.0.0"
+  }
+}
+```
+
+Every per-section response also carries `schema_version` inline
+(e.g. `ColorResolveResponse.schema_version`) so a consumer that
+hits the surface without first calling `/v1/contract` still has the
+information it needs to pick a validator.
+
+## Read-only invariants
+
+Codex never produces new PDF bytes. The invariant is enforced by
+`scripts/produce_surface_audit.py`, which fails CI when:
+
+- `pikepdf.new()` is invoked anywhere.
+- Any `Pdf.save(...)` call appears outside the documented
+  `apply_ocg_overrides` allowlist (a transient in-memory PDF fed
+  straight to Ghostscript with the requested OCG override applied;
+  bytes are never returned to a caller).
+- A producer package is imported (`pypdf`, `pdfrw`, `reportlab`,
+  `fpdf`, `fpdf2`, `pdfkit`, `borb`).
+- A Ghostscript invocation passes a PDF-writer device
+  (`-sDEVICE=pdfwrite`, `pdfimage8`, `pdfimage24`, `pdfimage32`).
+- `mutool {clean,create,merge}`, `qpdf` write modes, or `cpdf` is
+  invoked.
+- A `b"%PDF-"` literal is concatenated into output (read-only
+  sniffs like `raw[:5] == b"%PDF-"` are explicitly allowed).
+- `pikepdf` / `pymupdf` / `fitz` is imported outside the
+  allowlist (`codex_pdf.extract.*`, `codex_pdf.render.*`,
+  `codex_pdf.preflight_ingest.adapters`, `codex_pdf.eval.ps_type4`,
+  `codex_pdf.api.{main,url_ingest}`, `codex_pdf.parity`,
+  `codex_pdf.cli`).
+
+The audit emits a JSON report (`reports/audit/produce_surface.json`)
+on every CI run alongside the parity gate so reviewers can track
+status changes commit-by-commit.
+
+## Forge expansion rule
+
+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_pdf-1.4.2/docs/service-ownership-contract.md

@@ -0,0 +1,42 @@
+# Service Ownership Contract
+
+This contract defines ownership boundaries across the three OSS services:
+
+- `loupe-pdf`: display and visual inspection UX
+- `lint-pdf`: reporting, policy/rules, preflight workflow orchestration
+- `codex-pdf`: extraction and normalized document intelligence
+
+## Why this exists
+
+We keep implementation reusable and predictable by assigning each concern to one owner.
+UIs and new offshoots should consume stable service contracts instead of re-implementing logic.
+
+## Codex ownership (this repo)
+
+Codex owns deterministic extraction and normalized facts:
+
+- PDF structure extraction and source metadata
+- reusable `summary` payloads derived from extracted facts
+- detection signals that are not policy decisions (for example: candidate dieline layers)
+- versioned output contracts and backward-compatible evolution
+
+Codex does **not** own:
+
+- pass/fail policy, customer-specific thresholds, compliance verdicts
+- viewer rendering, layout interactions, review UX
+
+## Cross-service boundaries
+
+- Loupe consumes Codex/Lint data and renders it.
+- Lint consumes Codex signals and applies policy/rules/workflow semantics.
+- Codex remains rule-agnostic so multiple products can reuse it safely.
+
+## Future offshoot rule
+
+New projects (for example: Forge, Trap, Impose, Marks) MUST map each capability to one owner:
+
+1. Display/inspection UX -> Loupe layer
+2. Rules/reporting/workflow -> Lint layer
+3. Extraction/normalized intelligence -> Codex layer
+
+If a new feature spans layers, split it by contract; do not duplicate core logic across services.

{codex_pdf-1.4.0 → codex_pdf-1.4.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "codex-pdf"
-version = "1.4.0"
+version = "1.4.2"
 description = "Authoritative, versioned PDF facts contract for Think Neverland tools."
 readme = "README.md"
 requires-python = ">=3.12"