compile-pdf-cjd 0.1.0__tar.gz

compile_pdf_cjd-0.1.0/.coderabbit.yaml

@@ -0,0 +1,29 @@
+language: en-US
+reviews:
+  profile: chill
+  request_changes_workflow: false
+  high_level_summary: true
+  poem: false
+  review_status: true
+  collapse_walkthrough: true
+  auto_review:
+    enabled: true
+    drafts: false
+  path_filters:
+    - "!dist/**"
+    - "!build/**"
+    - "!.next/**"
+    - "!node_modules/**"
+    - "!**/__pycache__/**"
+    - "!**/*.min.js"
+    - "!**/*.lock"
+    - "!**/package-lock.json"
+    - "!**/uv.lock"
+    - "!**/poetry.lock"
+  path_instructions:
+    - path: "**/*.{ts,tsx,js,jsx}"
+      instructions: "Flag unhandled promises, missing null checks, hardcoded secrets/env vars, and unsafe `any` usage. Skip stylistic preferences — Prettier handles those."
+    - path: "**/*.py"
+      instructions: "Flag unhandled exceptions, missing type hints on public functions, hardcoded secrets, and SQL injection risks. Skip style — Ruff handles those."
+chat:
+  auto_reply: true

compile_pdf_cjd-0.1.0/.cursor/rules/baseline.mdc

@@ -0,0 +1,21 @@
+---
+description: PrintWithSynergy baseline rules
+alwaysApply: true
+---
+
+You are working in this repository, part of the printwithsynergy organization.
+
+# Conventions
+- Conventional commits (feat:, fix:, chore:, refactor:, docs:, test:)
+- Never commit secrets. Use .env (gitignored) for local config.
+- Prefer pure functions; isolate side effects.
+- Write tests alongside code changes when behavior changes.
+
+# Before modifying code
+- Use the code-review-graph MCP tools (get_impact_radius_tool, get_blast_radius) to check downstream impact.
+- For unfamiliar symbols, use sverklo_lookup or sverklo_refs first.
+- Never assume context. If the codebase has CLAUDE.md or AGENTS.md, read it first.
+
+# Style
+- Match existing code style. Do not reformat unrelated lines.
+- No "helper" refactors mixed with feature changes.

compile_pdf_cjd-0.1.0/.cursorrules

@@ -0,0 +1,16 @@
+You are working in the `compile-pdf-cjd` repository, part of the printwithsynergy organization.
+
+# Conventions
+- Conventional commits (feat:, fix:, chore:, refactor:, docs:, test:)
+- Never commit secrets. Use .env (gitignored) for local config.
+- Prefer pure functions; isolate side effects.
+- Write tests alongside code changes when behavior changes.
+
+# Before modifying code
+- Use the code-review-graph MCP tools (get_impact_radius_tool, get_blast_radius) to check downstream impact.
+- For unfamiliar symbols, use sverklo_lookup or sverklo_refs first.
+- Never assume context. If the codebase has CLAUDE.md or AGENTS.md, read it first.
+
+# Style
+- Match existing code style. Do not reformat unrelated lines.
+- No "helper" refactors mixed with feature changes.

compile_pdf_cjd-0.1.0/.github/dependabot.yml

@@ -0,0 +1,11 @@
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 5
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "monthly"

compile_pdf_cjd-0.1.0/.github/workflows/publish-pypi.yml

@@ -0,0 +1,39 @@
+name: publish-pypi
+
+# Publishes compile-pdf-cjd to PyPI when a v*.*.* tag is pushed.
+#
+# Auth: PyPI API token stored in PYPI_TOKEN repository secret.
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+
+jobs:
+  build:
+    name: build sdist + wheel
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
+        with:
+          python-version: "3.12"
+      - run: pip install --upgrade pip build
+      - run: python -m build --sdist --wheel --outdir dist/
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: dist
+          path: dist/*
+
+  publish:
+    name: publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # release/v1
+        with:
+          password: ${{ secrets.PYPI_TOKEN }}

compile_pdf_cjd-0.1.0/.gitignore

@@ -0,0 +1,5 @@
+__pycache__/
+*.py[cod]
+dist/
+*.egg-info/
+.pytest_cache/

compile_pdf_cjd-0.1.0/CLAUDE.md

@@ -0,0 +1,9 @@
+# compile-pdf-cjd
+
+compile-pdf-cjd
+
+## Code Review & Blast-Radius Protocol
+- Before edits: run code-review-graph impact tools on changed symbols
+- After edits: ensure tests pass before commit
+- CodeRabbit reviews PRs automatically; Cursor BugBot provides second opinion
+- Never disable the code-review-graph Launch Agent

compile_pdf_cjd-0.1.0/PKG-INFO

@@ -0,0 +1,63 @@
+Metadata-Version: 2.4
+Name: compile-pdf-cjd
+Version: 0.1.0
+Summary: CompilePDF CJD orchestrator — sequences trap, impose, marks, and rewrite producers in a single Compile Job Definition.
+Project-URL: Homepage, https://compilepdf.com
+Project-URL: Repository, https://github.com/printwithsynergy/compile-pdf-cjd
+Project-URL: Issues, https://github.com/printwithsynergy/compile-pdf-cjd/issues
+Author-email: Print With Synergy <iam@quincy.codes>
+License: AGPL-3.0-or-later
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Multimedia :: Graphics
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.12
+Requires-Dist: click>=8.1
+Requires-Dist: compile-pdf-core<1.0,>=0.1.0
+Requires-Dist: compile-pdf-impose<1.0,>=0.1.0
+Requires-Dist: compile-pdf-marks<1.0,>=0.1.0
+Requires-Dist: compile-pdf-rewrite<1.0,>=0.1.0
+Requires-Dist: compile-pdf-trap<1.0,>=0.1.0
+Requires-Dist: defusedxml>=0.7.1
+Requires-Dist: fastapi>=0.110
+Requires-Dist: pydantic>=2.6
+Requires-Dist: structlog>=24.1
+Provides-Extra: dev
+Requires-Dist: mypy>=1.9; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-cov>=4.1; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# compile-pdf-cjd
+
+CJD orchestrator — sequences all four CompilePDF producers (trap, rewrite, marks, impose) in one job.
+
+Compile Job Definition: a JSON/XML envelope that bundles a multi-producer run into a single submission. Sequences `trap → rewrite → marks → impose` with lineage threading across every stage. XML + JSON formats; each stage's diff artifact is stored in the lineage record.
+
+## Install
+
+```bash
+uv pip install compile-pdf-cjd
+```
+
+This package depends on the four producer packages plus `compile-pdf-core`; installing it pulls the whole orchestrator chain.
+
+## Position in the stack
+
+The only CompilePDF package that imports all four producers. Stand-alone producers live in their own repos:
+
+- https://github.com/printwithsynergy/compile-pdf-trap
+- https://github.com/printwithsynergy/compile-pdf-rewrite
+- https://github.com/printwithsynergy/compile-pdf-marks
+- https://github.com/printwithsynergy/compile-pdf-impose
+- https://github.com/printwithsynergy/compile-pdf-core
+
+- Repo: https://github.com/printwithsynergy/compile-pdf-cjd
+- Deployment host: https://github.com/printwithsynergy/compile-pdf
+- Marketing: https://compilepdf.com
+- License: AGPL-3.0-or-later

compile_pdf_cjd-0.1.0/README.md

@@ -0,0 +1,28 @@
+# compile-pdf-cjd
+
+CJD orchestrator — sequences all four CompilePDF producers (trap, rewrite, marks, impose) in one job.
+
+Compile Job Definition: a JSON/XML envelope that bundles a multi-producer run into a single submission. Sequences `trap → rewrite → marks → impose` with lineage threading across every stage. XML + JSON formats; each stage's diff artifact is stored in the lineage record.
+
+## Install
+
+```bash
+uv pip install compile-pdf-cjd
+```
+
+This package depends on the four producer packages plus `compile-pdf-core`; installing it pulls the whole orchestrator chain.
+
+## Position in the stack
+
+The only CompilePDF package that imports all four producers. Stand-alone producers live in their own repos:
+
+- https://github.com/printwithsynergy/compile-pdf-trap
+- https://github.com/printwithsynergy/compile-pdf-rewrite
+- https://github.com/printwithsynergy/compile-pdf-marks
+- https://github.com/printwithsynergy/compile-pdf-impose
+- https://github.com/printwithsynergy/compile-pdf-core
+
+- Repo: https://github.com/printwithsynergy/compile-pdf-cjd
+- Deployment host: https://github.com/printwithsynergy/compile-pdf
+- Marketing: https://compilepdf.com
+- License: AGPL-3.0-or-later

compile_pdf_cjd-0.1.0/pyproject.toml

@@ -0,0 +1,72 @@
+[project]
+name = "compile-pdf-cjd"
+version = "0.1.0"
+description = "CompilePDF CJD orchestrator — sequences trap, impose, marks, and rewrite producers in a single Compile Job Definition."
+readme = "README.md"
+license = { text = "AGPL-3.0-or-later" }
+authors = [{ name = "Print With Synergy", email = "iam@quincy.codes" }]
+requires-python = ">=3.12"
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Multimedia :: Graphics",
+  "Topic :: Software Development :: Libraries",
+]
+
+dependencies = [
+  "compile-pdf-core>=0.1.0,<1.0",
+  "compile-pdf-trap>=0.1.0,<1.0",
+  "compile-pdf-impose>=0.1.0,<1.0",
+  "compile-pdf-marks>=0.1.0,<1.0",
+  "compile-pdf-rewrite>=0.1.0,<1.0",
+  "fastapi>=0.110",
+  "pydantic>=2.6",
+  "click>=8.1",
+  "structlog>=24.1",
+  "defusedxml>=0.7.1",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8.0",
+  "pytest-asyncio>=0.23",
+  "pytest-cov>=4.1",
+  "ruff>=0.4",
+  "mypy>=1.9",
+]
+
+[project.scripts]
+compile-pdf-cjd = "compile_pdf_cjd.cli:main"
+
+[project.urls]
+Homepage = "https://compilepdf.com"
+Repository = "https://github.com/printwithsynergy/compile-pdf-cjd"
+Issues = "https://github.com/printwithsynergy/compile-pdf-cjd/issues"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/compile_pdf_cjd"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "W", "UP", "B", "SIM", "C4", "RET"]
+ignore = ["E501"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+addopts = ["-ra", "--strict-markers", "--strict-config"]
+asyncio_mode = "auto"
+
+[tool.coverage.run]
+source = ["src/compile_pdf_cjd"]
+branch = true

compile_pdf_cjd-0.1.0/src/compile_pdf_cjd/api.py

@@ -0,0 +1,209 @@
+"""FastAPI router for the CJD pipeline + lineage lookup.
+
+Mounts:
+
+* ``POST /v1/cjd/apply`` — execute a CJD job
+* ``GET  /v1/lineage/{lineage_id}`` — fetch a chain by id
+* ``GET  /v1/lineage`` — list known lineage ids (paginated)
+
+Pass ``?async=true`` on ``POST /v1/cjd/apply`` to submit the job to
+Celery and receive a ``202`` with a ``job_id`` you can poll at
+``GET /v1/jobs/{job_id}``.
+"""
+
+from __future__ import annotations
+
+import base64
+
+import structlog
+from fastapi import APIRouter, HTTPException, Query, Request, status
+from pydantic import BaseModel
+
+from compile_pdf_cjd.orchestrator import CjdOrderError, execute
+from compile_pdf_cjd.schema import CjdJob
+from compile_pdf_cjd.xml import CjdXmlError, parse_cjd_xml
+from compile_pdf_core.async_jobs import AsyncJobAccepted, JobStatus, create_job
+from compile_pdf_core.lineage.store import (
+    LineageNotFoundError,
+    default_store,
+    serialize_chain,
+)
+from compile_pdf_core.retention import parse_consent, resolve_tenant
+from compile_pdf_core.tasks import task_payload_hash
+from compile_pdf_core.version import (
+    CJD_SCHEMA_VERSION,
+    VERSION,
+)
+
+logger = structlog.get_logger(__name__)
+
+cjd_router = APIRouter()
+lineage_router = APIRouter()
+
+
+class CjdApplyResponse(BaseModel):
+    model_config = {"extra": "forbid"}
+
+    output_pdf_b64: str
+    output_pdf_sha256: str
+    lineage_id: str
+    steps: list[dict[str, object]]
+    trap_diff: dict[str, object] | None = None
+    schema_version: str = CJD_SCHEMA_VERSION
+    compile_version: str = VERSION
+
+
+@cjd_router.post(
+    "/apply",
+    response_model=CjdApplyResponse,
+    status_code=status.HTTP_200_OK,
+    responses={202: {"model": AsyncJobAccepted}},
+)
+async def cjd_apply(
+    job: CjdJob,
+    request: Request,
+    async_: bool = Query(False, alias="async"),
+) -> CjdApplyResponse | AsyncJobAccepted:
+    """Execute a CJD job: orchestrate the four producers in dependency
+    order, persist lineage records, return the final PDF + chain.
+
+    Pass ``?async=true`` to enqueue the job on Celery and receive a ``202``
+    ``AsyncJobAccepted`` response. Poll ``GET /v1/jobs/{job_id}`` until the
+    status is ``complete`` or ``failed``.
+    """
+    if async_:
+        job_payload = job.model_dump(mode="json")
+        ph = task_payload_hash(job_payload)
+        job_id = create_job(kind="cjd", payload_hash=ph)
+        from compile_pdf_core.async_tasks import async_wrap_cjd
+
+        async_wrap_cjd.apply_async(args=[job_id, job_payload])
+        logger.info("cjd.apply.async_accepted", job_id=job_id, payload_hash=ph[:16])
+        from fastapi.responses import JSONResponse
+
+        return JSONResponse(  # type: ignore[return-value]
+            status_code=status.HTTP_202_ACCEPTED,
+            content=AsyncJobAccepted(
+                job_id=job_id,
+                status=JobStatus.pending,
+                poll_url=f"/v1/jobs/{job_id}",
+            ).model_dump(),
+        )
+
+    consent = parse_consent(request)
+    tenant = resolve_tenant(request)
+    try:
+        result = execute(job, consent=consent, tenant=tenant)
+    except CjdOrderError as exc:
+        raise HTTPException(status_code=422, detail=f"CJD ordering rejected: {exc}") from exc
+    except (ValueError, TypeError) as exc:
+        # Includes base64 errors from inside execute().
+        raise HTTPException(status_code=400, detail=f"CJD job rejected: {exc}") from exc
+
+    logger.info(
+        "cjd.apply.ok",
+        lineage_id=result.lineage_id,
+        steps=len(result.steps),
+        output_sha=result.output_pdf_sha256[:16],
+        consent=consent,
+        retained_steps=sum(1 for s in result.steps if s.retained_for_training),
+    )
+
+    return CjdApplyResponse(
+        output_pdf_b64=base64.b64encode(result.output_pdf_bytes).decode("ascii"),
+        output_pdf_sha256=result.output_pdf_sha256,
+        lineage_id=result.lineage_id,
+        steps=[_step_to_dict(s) for s in result.steps],
+        trap_diff=result.trap_diff,
+    )
+
+
+@cjd_router.post(
+    "/apply-xml",
+    response_model=CjdApplyResponse,
+    status_code=status.HTTP_200_OK,
+)
+async def cjd_apply_xml(request: Request) -> CjdApplyResponse:
+    """XML-encoded variant of POST /v1/cjd/apply.
+
+    Body is a CJD XML envelope (per :mod:`compile_pdf.cjd.xml`); the
+    response shape matches the JSON endpoint exactly. Useful for
+    operators integrating Compile into JDF / PJTF pipelines that
+    already speak XML on the wire.
+    """
+    body = await request.body()
+    if not body:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="empty XML body")
+    try:
+        job = parse_cjd_xml(body)
+    except CjdXmlError as exc:
+        raise HTTPException(status_code=422, detail=f"CJD XML rejected: {exc}") from exc
+
+    consent = parse_consent(request)
+    tenant = resolve_tenant(request)
+    try:
+        result = execute(job, consent=consent, tenant=tenant)
+    except CjdOrderError as exc:
+        raise HTTPException(status_code=422, detail=f"CJD ordering rejected: {exc}") from exc
+    except (ValueError, TypeError) as exc:
+        raise HTTPException(status_code=400, detail=f"CJD job rejected: {exc}") from exc
+
+    logger.info(
+        "cjd.apply_xml.ok",
+        lineage_id=result.lineage_id,
+        steps=len(result.steps),
+        output_sha=result.output_pdf_sha256[:16],
+        consent=consent,
+        retained_steps=sum(1 for s in result.steps if s.retained_for_training),
+    )
+
+    return CjdApplyResponse(
+        output_pdf_b64=base64.b64encode(result.output_pdf_bytes).decode("ascii"),
+        output_pdf_sha256=result.output_pdf_sha256,
+        lineage_id=result.lineage_id,
+        steps=[_step_to_dict(s) for s in result.steps],
+        trap_diff=result.trap_diff,
+    )
+
+
+class LineageListResponse(BaseModel):
+    model_config = {"extra": "forbid"}
+
+    lineage_ids: list[str]
+
+
+@lineage_router.get("/{lineage_id}", status_code=status.HTTP_200_OK)
+async def lineage_get(lineage_id: str) -> dict[str, object]:
+    """Fetch a lineage chain by id."""
+    try:
+        chain = default_store().get(lineage_id)
+    except LineageNotFoundError as exc:
+        raise HTTPException(status_code=404, detail=f"lineage_id not found: {lineage_id}") from exc
+    return serialize_chain(chain)
+
+
+@lineage_router.get(
+    "",
+    response_model=LineageListResponse,
+    status_code=status.HTTP_200_OK,
+)
+async def lineage_list(limit: int = Query(default=50, ge=1, le=500)) -> LineageListResponse:
+    """List known lineage ids (best-effort; backend may paginate)."""
+    return LineageListResponse(lineage_ids=default_store().list_ids(limit=limit))
+
+
+def _step_to_dict(step) -> dict[str, object]:  # type: ignore[no-untyped-def]
+    payload: dict[str, object] = {
+        "step_index": step.step_index,
+        "producer": step.producer,
+        "input_sha256": step.input_sha256,
+        "output_sha256": step.output_sha256,
+        "cache_key": step.cache_key,
+        "plan_sha256": step.plan_sha256,
+        "retained_for_training": step.retained_for_training,
+    }
+    if step.extras:
+        payload["extras"] = dict(step.extras)
+    if step.trap_diff is not None:
+        payload["trap_diff"] = step.trap_diff
+    return payload

compile_pdf_cjd-0.1.0/src/compile_pdf_cjd/cli.py

@@ -0,0 +1,170 @@
+"""Click subcommand registration for ``compile-pdf cjd`` + ``lineage``."""
+
+from __future__ import annotations
+
+import base64
+import json
+import sys
+from pathlib import Path
+
+import click
+
+from compile_pdf_cjd.orchestrator import CjdOrderError, execute
+from compile_pdf_cjd.schema import CjdJob, cjd_job_json_schema
+from compile_pdf_cjd.xml import CjdXmlError, parse_cjd_xml, render_cjd_xml
+from compile_pdf_core.lineage.store import (
+    LineageNotFoundError,
+    default_store,
+    serialize_chain,
+)
+
+
+def register(group: click.Group) -> None:
+    """Attach ``cjd``, ``cjd-schema``, and ``lineage`` subcommands."""
+
+    @group.command("cjd", help="Execute a CJD job (multi-producer pipeline).")
+    @click.option(
+        "--job",
+        "job_path",
+        type=click.Path(exists=True, dir_okay=False, path_type=Path),
+        required=True,
+        help="JSON CJD-job document.",
+    )
+    @click.option(
+        "--input",
+        "input_path",
+        type=click.Path(exists=True, dir_okay=False, path_type=Path),
+        default=None,
+        help=(
+            "Optional. When set, the input PDF bytes are read from this "
+            "path and replace job.input_pdf_b64 (handy for large inputs)."
+        ),
+    )
+    @click.option(
+        "--trap-diff",
+        "trap_diff_path",
+        type=click.Path(dir_okay=False, path_type=Path),
+        default=None,
+        help="Write the trap-diff artifact to this path (no-op if no trap step).",
+    )
+    @click.option(
+        "--xml/--json",
+        "use_xml",
+        default=False,
+        help="Read the job document as XML (default: JSON).",
+    )
+    @click.argument(
+        "output_path",
+        type=click.Path(dir_okay=False, path_type=Path),
+    )
+    def cjd_cmd(
+        job_path: Path,
+        input_path: Path | None,
+        trap_diff_path: Path | None,
+        use_xml: bool,
+        output_path: Path,
+    ) -> None:
+        if use_xml:
+            try:
+                job = parse_cjd_xml(job_path.read_bytes())
+            except CjdXmlError as exc:
+                click.echo(f"XML job rejected: {exc}", err=True)
+                sys.exit(3)
+            if input_path is not None:
+                # Re-serialize with the override and re-parse via JSON path.
+                payload = job.model_dump(mode="json")
+                payload["input_pdf_b64"] = base64.b64encode(input_path.read_bytes()).decode("ascii")
+                job = CjdJob.model_validate(payload)
+        else:
+            job_dict = json.loads(job_path.read_text(encoding="utf-8"))
+            if input_path is not None:
+                job_dict["input_pdf_b64"] = base64.b64encode(input_path.read_bytes()).decode(
+                    "ascii"
+                )
+            try:
+                job = CjdJob.model_validate(job_dict)
+            except Exception as exc:
+                click.echo(f"job validation failed: {exc}", err=True)
+                sys.exit(3)
+
+        try:
+            result = execute(job)
+        except CjdOrderError as exc:
+            click.echo(f"job rejected: {exc}", err=True)
+            sys.exit(4)
+
+        output_path.write_bytes(result.output_pdf_bytes)
+        if trap_diff_path is not None and result.trap_diff is not None:
+            trap_diff_path.write_text(json.dumps(result.trap_diff, indent=2), encoding="utf-8")
+
+        click.echo(
+            json.dumps(
+                {
+                    "lineage_id": result.lineage_id,
+                    "output_pdf_sha256": result.output_pdf_sha256,
+                    "steps": [
+                        {
+                            "step_index": s.step_index,
+                            "producer": s.producer,
+                            "output_sha256": s.output_sha256[:16],
+                            "cache_key": s.cache_key[:16],
+                        }
+                        for s in result.steps
+                    ],
+                    "output": str(output_path),
+                    "trap_diff": str(trap_diff_path)
+                    if trap_diff_path and result.trap_diff is not None
+                    else None,
+                },
+                indent=2,
+            )
+        )
+
+    @group.command("cjd-schema", hidden=True, help="Dump the CJD-job JSON Schema.")
+    def cjd_schema_cmd() -> None:
+        click.echo(json.dumps(cjd_job_json_schema(), indent=2))
+
+    @group.command(
+        "cjd-xml-render",
+        hidden=True,
+        help="Convert a JSON CJD job to XML and print the result.",
+    )
+    @click.argument(
+        "job_path",
+        type=click.Path(exists=True, dir_okay=False, path_type=Path),
+    )
+    def cjd_xml_render_cmd(job_path: Path) -> None:
+        job_dict = json.loads(job_path.read_text(encoding="utf-8"))
+        try:
+            job = CjdJob.model_validate(job_dict)
+        except Exception as exc:
+            click.echo(f"job validation failed: {exc}", err=True)
+            sys.exit(3)
+        click.echo(render_cjd_xml(job).decode("utf-8"))
+
+    @group.command("lineage", help="Print the lineage chain for a previously-run CJD job.")
+    @click.argument("lineage_id", type=str)
+    @click.option(
+        "--chain/--summary",
+        default=False,
+        help="Print the full chain (default) vs. just the lineage_id + step count.",
+    )
+    def lineage_cmd(lineage_id: str, chain: bool) -> None:
+        try:
+            ch = default_store().get(lineage_id)
+        except LineageNotFoundError:
+            click.echo(f"lineage_id not found: {lineage_id}", err=True)
+            sys.exit(5)
+        if chain:
+            click.echo(json.dumps(serialize_chain(ch), indent=2))
+        else:
+            click.echo(
+                json.dumps(
+                    {
+                        "lineage_id": ch.lineage_id,
+                        "step_count": len(ch.steps),
+                        "producers": [s.producer for s in ch.steps],
+                    },
+                    indent=2,
+                )
+            )