Skip to main content

Preflight Artifact Contract

The Preflight Artifact Contract establishes the canonical specifications, resolution protocols, naming conventions, and error handling behaviors for physical document assets generated and consumed across PrintPrice OS.

Aligning the Preflight Service, Worker, BFF, and ControlPlane to this contract ensures that physical files remain traceable, immutable, and consistent with database registries.

Our artifact pipeline is governed by the platform's core operational promise:

Engine produces truth. Service preserves truth. Worker executes and persists truth. BFF displays truth. ControlPlane governs truth.

1. Canonical Artifact Types​

Every physical asset in the preflight pipeline is categorized into one of five canonical artifact definitions:

analysis_report​

  • Canonical File Name: report.json
  • Operational Requirement: Strictly mandatory for all completed or degraded analysis attempts.
  • Contents: Represents the absolute diagnostic truth extracted by the parsing engine, detailing document structures, warnings, and error counts.

certified_pdf​

  • Canonical File Name: certified.pdf
  • Operational Requirement: Only present when a document is officially validated as printable.
  • Security Constraint: Must not be generated or promoted if the document contains blocking violations or preflight failures.

final_fixed_pdf​

  • Canonical File Name: A logical routing alias mapped to the final corrected document output.
  • Resolution Priority: When a downstream process requests the final_fixed_pdf alias, the system resolves it using the following strict priority:
    1. fixed.pdf (Direct vector autofix result, if present)
    2. normalized.pdf (Color-profile and bleed normalized PDF, if present)
    3. certified.pdf (The original validated document, if no repair was needed)

fixed_pdf​

  • Canonical File Name: fixed.pdf
  • Operational Requirement: A compatibility alias pointing directly to the successfully auto-repaired PDF output.

fix_audit​

  • Canonical File Name: fix_audit.json
  • Operational Requirement: Houses audit traces detailing requested, applied, skipped, or failed fixes for autofix execution lifecycles.

2. Analysis Artifacts​

For all ANALYZE execution jobs, the pipeline enforces strict artifact generation limits:

  • Primary Artifact: The analysis_report (report.json) is the singular primary artifact. It must be generated and persisted for every completed run.
  • Validated PDF Gating: The generation of certified_pdf (certified.pdf) is optional and must be tightly gated.
  • Degraded Mode Support: A document that is non-certifiable (such as a file containing color violations) can still terminate with a DEGRADED or COMPLETED_WITH_FINDINGS status and successfully write its analysis_report (report.json), allowing pricing and review processes to proceed.

3. Autofix Artifacts​

For all AUTOFIX repair jobs, the worker node executes vector manipulations and structures its outputs:

  • Logical Resolution: The final_fixed_pdf alias must be dynamically resolved to the highest available repaired asset.
  • Compatibility Alias: The compatibility alias fixed_pdf must point to the physical fixed.pdf generated by vector processing.
  • Autofix Lifecycle Audit: The worker must compile and upload fix_audit.json detailing the autofix diagnostics. The audit must explicitly segment:
    • Requested Fixes: Anomalies sent for automated correction.
    • Applied Fixes: Vector repairs successfully executed and validated on the document.
    • Skipped Fixes: Repairs that were skipped because the document state rendered them redundant.
    • Failed Fixes: Anomaly repairs that were attempted but aborted due to validation exceptions.

4. Error Contract​

When a downstream user or service requests a physical file that cannot be retrieved from object storage, the system must trigger a strict ARTIFACT_NOT_FOUND error contract.

To prevent telemetry loss, the ARTIFACT_NOT_FOUND payload must preserve the following details:

{
  "error": "ARTIFACT_NOT_FOUND",
  "message": "The requested artifact could not be resolved in persistent storage.",
  "jobId": "job_1779116602472_1d246",
  "artifactId": "art_final_fixed_pdf_08",
  "requestedAlias": "final_fixed_pdf",
  "availableArtifacts": [
    "analysis_report"
  ]
}
warning

Anti-Collapse Rule: Under no circumstances may the BFF/App or ControlPlane collapse these specific JSON error payloads into a generic "500 Internal Server Error" or generic stream failure. The detailed error envelope must be preserved and exposed to allow administrative diagnostics.

5. Production Validation Case Study​

The integrity of this artifact contract has been verified in our active production environment through the audit of the following automated PDF repair execution:

Validated Autofix Record​

  • Fix Identifier (fixId): fix_1779116602946
  • Source Preflight Job ID (sourceJobId): job_1779116602472_1d246
  • Job Execution Status: COMPLETED
  • Output Resolution: Mapped artifacts.final_fixed_pdf directly to the newly written physical asset fixed.pdf.
  • Repairs Count: 4
  • Applied Repairs Count: 4 (100% execution validation)
  • Skipped Repairs Count: 0
  • Failed Repairs Count: 0