@photivra/engine 1.0.1 → 1.2.0

package/docs/api/optics-scene-to-sensor-irradiance.md

@@ -1,6 +1,6 @@
 # optics/scene-to-sensor-irradiance.ts public contracts
 
-Package **1.0.1**, root API **1.0.1**. [Navigation](../API_REFERENCE.md) · [Developer guide](../DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
+Package **1.2.0**, root API **1.2.0**. [Navigation](../API_REFERENCE.md) · [Developer guide](../DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
 
 ## calculateSceneRadianceToSensorIrradiance
 

package/docs/api/optics-scene-to-sensor-quadrature.md

@@ -1,6 +1,6 @@
 # optics/scene-to-sensor-quadrature.ts public contracts
 
-Package **1.0.1**, root API **1.0.1**. [Navigation](../API_REFERENCE.md) · [Developer guide](../DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
+Package **1.2.0**, root API **1.2.0**. [Navigation](../API_REFERENCE.md) · [Developer guide](../DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
 
 ## calculateSceneToSensorIrradianceQuadrature
 

package/docs/api/optics-sensor-environment-query.md

@@ -1,6 +1,6 @@
 # optics/sensor-environment-query.ts public contracts
 
-Package **1.0.1**, root API **1.0.1**. [Navigation](../API_REFERENCE.md) · [Developer guide](../DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
+Package **1.2.0**, root API **1.2.0**. [Navigation](../API_REFERENCE.md) · [Developer guide](../DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
 
 ## calculateSensorEnvironmentRadianceQuery
 

package/docs/api/optics-sensor-psf-quadrature.md

@@ -1,6 +1,6 @@
 # optics/sensor-psf-quadrature.ts public contracts
 
-Package **1.0.1**, root API **1.0.1**. [Navigation](../API_REFERENCE.md) · [Developer guide](../DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
+Package **1.2.0**, root API **1.2.0**. [Navigation](../API_REFERENCE.md) · [Developer guide](../DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
 
 ## calculateSensorPsfIrradianceQuadrature
 

package/docs/api/optics-stray-light.md

@@ -1,6 +1,6 @@
 # optics/stray-light.ts public contracts
 
-Package **1.0.1**, root API **1.0.1**. [Navigation](../API_REFERENCE.md) · [Developer guide](../DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
+Package **1.2.0**, root API **1.2.0**. [Navigation](../API_REFERENCE.md) · [Developer guide](../DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
 
 ## calculateLensStrayLightIrradiance
 

package/docs/api/optics-thin-lens.md

@@ -1,6 +1,6 @@
 # optics/thin-lens.ts public contracts
 
-Package **1.0.1**, root API **1.0.1**. [Navigation](../API_REFERENCE.md) · [Developer guide](../DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
+Package **1.2.0**, root API **1.2.0**. [Navigation](../API_REFERENCE.md) · [Developer guide](../DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
 
 ## calculateThinLensImageDistance
 

package/docs/api/output-capture-corrected-sdr.md

@@ -1,6 +1,6 @@
 # output/capture-corrected-sdr.ts public contracts
 
-Package **1.0.1**, root API **1.0.1**. [Navigation](../API_REFERENCE.md) · [Developer guide](../DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
+Package **1.2.0**, root API **1.2.0**. [Navigation](../API_REFERENCE.md) · [Developer guide](../DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
 
 ## calculateCaptureCorrectedSdr
 

package/docs/api/output-capture-geometry.md

@@ -1,6 +1,6 @@
 # output/capture-geometry.ts public contracts
 
-Package **1.0.1**, root API **1.0.1**. [Navigation](../API_REFERENCE.md) · [Developer guide](../DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
+Package **1.2.0**, root API **1.2.0**. [Navigation](../API_REFERENCE.md) · [Developer guide](../DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
 
 ## ActiveCaptureFieldOfView
 

package/docs/api/output-capture-sdr.md

@@ -1,6 +1,6 @@
 # output/capture-sdr.ts public contracts
 
-Package **1.0.1**, root API **1.0.1**. [Navigation](../API_REFERENCE.md) · [Developer guide](../DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
+Package **1.2.0**, root API **1.2.0**. [Navigation](../API_REFERENCE.md) · [Developer guide](../DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
 
 ## calculateCaptureSdr
 

package/docs/api/output-crop.md

@@ -1,6 +1,6 @@
 # output/crop.ts public contracts
 
-Package **1.0.1**, root API **1.0.1**. [Navigation](../API_REFERENCE.md) · [Developer guide](../DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
+Package **1.2.0**, root API **1.2.0**. [Navigation](../API_REFERENCE.md) · [Developer guide](../DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
 
 ## calculateCenteredCrop
 

package/docs/api/output-geometric-transforms.md

@@ -1,6 +1,6 @@
 # output/geometric-transforms.ts public contracts
 
-Package **1.0.1**, root API **1.0.1**. [Navigation](../API_REFERENCE.md) · [Developer guide](../DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
+Package **1.2.0**, root API **1.2.0**. [Navigation](../API_REFERENCE.md) · [Developer guide](../DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
 
 ## AffineGeometricTransform
 

package/docs/api/output-lens-corrections.md

@@ -1,6 +1,6 @@
 # output/lens-corrections.ts public contracts
 
-Package **1.0.1**, root API **1.0.1**. [Navigation](../API_REFERENCE.md) · [Developer guide](../DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
+Package **1.2.0**, root API **1.2.0**. [Navigation](../API_REFERENCE.md) · [Developer guide](../DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
 
 ## calculateLensCorrectedCapture
 

package/docs/api/output-native-capture-sdr.md

@@ -0,0 +1,150 @@
+# output/native-capture-sdr.ts public contracts
+
+Package **1.2.0**, root API **1.2.0**. [Navigation](../API_REFERENCE.md) · [Developer guide](../DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
+
+## calculateNativeCaptureSdrPlan
+
+Validates/admission-plans without reading external samples or allocating a raster.
+
+```ts
+export function calculateNativeCaptureSdrPlan(input: NativeCaptureSdrInput): NativeCaptureSdrPlan;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## createNativeCaptureSdrTask
+
+Creates a single-use execution owner. Admission is validated before any buffer/provider work.
+
+```ts
+export function createNativeCaptureSdrTask(input: NativeCaptureSdrInput, provider: NativeCaptureSdrProvider): NativeCaptureSdrTask;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## NATIVE_CAPTURE_SDR_LIMITS
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+NATIVE_CAPTURE_SDR_LIMITS = Object.freeze({ maximumPixels: 24_000_000,
+  maximumDimension: 16_384, tileWidth: 256, tileHeight: 32, maximumTileStorageSamples: 32_768 })
+```
+
+## NATIVE_CAPTURE_SDR_SCHEMA_VERSION
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+NATIVE_CAPTURE_SDR_SCHEMA_VERSION = "0.1.0" as const
+```
+
+## NativeCaptureSdrInput
+
+Metadata-only external float master. Samples must already be color/WB resolved.
+
+```ts
+export interface NativeCaptureSdrInput {
+  capture: SimulatedCapture;
+  sourcePlaneId: string;
+  outputImageStateId: string;
+  profile: SdrRenderingProfile;
+  /** Admission limit for retained integer output, before allocation or provider calls. */
+  maximumOutputBytes: number;
+}
+```
+
+## NativeCaptureSdrOutput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface NativeCaptureSdrOutput {
+  plan: NativeCaptureSdrPlan;
+  /** Caller-owned packed row-major RGB; 16-bit codes are numeric, not serialized endian bytes. */
+  integerSamples: Uint8Array | Uint16Array;
+  diagnostics: SdrRenderingResult["diagnostics"];
+  outputEncoding: SdrRenderingResult["outputEncoding"];
+  displayAdaptation: SdrRenderingResult["displayAdaptation"];
+}
+```
+
+## NativeCaptureSdrPlan
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface NativeCaptureSdrPlan {
+  schemaVersion: typeof NATIVE_CAPTURE_SDR_SCHEMA_VERSION;
+  capture: SimulatedCapture;
+  sourcePlaneId: string;
+  outputImageStateId: string;
+  profile: SdrRenderingProfile;
+  outputBytes: number;
+  /** Logical array payload bound, not JS heap/GPU/process peak memory or device qualification. */
+  maximumScratchPayloadBytes: number;
+  tileCount: number;
+}
+```
+
+## NativeCaptureSdrProvider
+
+One provider call at a time. Caller must release decoding/GPU resources on abort/settlement.
+
+```ts
+export interface NativeCaptureSdrProvider {
+  readTile(request: Readonly<NativeCaptureSdrTileRequest>, signal: AbortSignal): Promise<NativeCaptureSdrTile>;
+  /** Must yield to the host event loop, allowing cancellation/input events between tiles. */
+  yieldControl(signal: AbortSignal): Promise<void>;
+}
+```
+
+## NativeCaptureSdrTask
+
+Single-use task: no partial output escapes; cancel/dispose prevents late publication.
+
+```ts
+export interface NativeCaptureSdrTask {
+  readonly plan: NativeCaptureSdrPlan;
+  readonly state: NativeCaptureSdrTaskState;
+  readonly completedTileCount: number;
+  run(): Promise<void>;
+  cancel(): void;
+  dispose(): void;
+  /** Transfers sole retained buffer ownership once. Dispose cannot revoke a transferred buffer. */
+  takeOutput(): NativeCaptureSdrOutput;
+}
+```
+
+## NativeCaptureSdrTaskState
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type NativeCaptureSdrTaskState = "ready" | "running" | "completed" | "cancelled" | "failed" | "disposed" | "transferred";
+```
+
+## NativeCaptureSdrTile
+
+Returned tile is exclusively handed to this call; do not mutate/reuse it. Padding is not image data.
+
+```ts
+export interface NativeCaptureSdrTile extends NativeCaptureSdrTileRequest {
+  rowStrideSamples: number;
+  samples: Float32Array | Float64Array;
+}
+```
+
+## NativeCaptureSdrTileRequest
+
+Absolute coordinates in the selected plane's declared binding, never crop-local sensor indices.
+
+```ts
+export interface NativeCaptureSdrTileRequest {
+  captureId: string;
+  sourcePlaneId: string;
+  artifactId: string;
+  sha256: string;
+  x: number; y: number; width: number; height: number;
+}
+```

package/docs/api/output-print-contrast-reference.md

@@ -0,0 +1,82 @@
+# output/print-contrast-reference.ts public contracts
+
+Package **1.2.0**, root API **1.2.0**. [Navigation](../API_REFERENCE.md) · [Developer guide](../DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
+
+## calculatePrintContrastReference
+
+Estimate the restricted published-model threshold; no individual invisibility claim.
+
+```ts
+export function calculatePrintContrastReference(value: PrintContrastReferenceInput): CalculationResult<PrintContrastReference>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## parsePrintContrastReferenceInput
+
+Strictly parse/copy explicit reference conditions; no defaults infer an observer.
+
+```ts
+export function parsePrintContrastReferenceInput(value: unknown): PrintContrastReferenceInput;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## PRINT_CONTRAST_REFERENCE_MODEL_VERSION
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+PRINT_CONTRAST_REFERENCE_MODEL_VERSION = "0.1.0" as const
+```
+
+## PRINT_CONTRAST_REFERENCE_UPSTREAM_REVISION
+
+Exact MIT-licensed numerical-model source, not a local calibration identity.
+
+```ts
+PRINT_CONTRAST_REFERENCE_UPSTREAM_REVISION = "f4b0b722af83001d7af979281e06ca642d36e4e8" as const
+```
+
+## PrintContrastReference
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface PrintContrastReference {
+  referenceId: string;
+  engineApiVersion: string;
+  modelVersion: typeof PRINT_CONTRAST_REFERENCE_MODEL_VERSION;
+  upstreamRevision: typeof PRINT_CONTRAST_REFERENCE_UPSTREAM_REVISION;
+  input: PrintContrastReferenceInput;
+  status: "model-estimate" | "unsupported";
+  blockers: string[];
+  estimate: { contrastSensitivity: number; thresholdModulationMichelson: number; suppliedModulationToModelThresholdRatio: number } | null;
+  observerApplicability: "population-reference-unverified-for-individual";
+  naturalImageVisibility: "unassessed";
+  printStimulusMatch: "unassessed";
+  uncertainty: "not-quantified";
+  overallPrintVerdict: "not-offered";
+}
+```
+
+## PrintContrastReferenceInput
+
+Narrow reference stimulus, separate from any measured photographic ROI.
+Positive but out-of-domain quantities return unsupported rather than extrapolation.
+
+```ts
+export interface PrintContrastReferenceInput {
+  referenceId: string;
+  stimulus: "static-neutral-d65-gabor";
+  observer: "published-binocular-natural-pupil-reference";
+  /** Uniform D65 background/carrier mean; not the average of a finite photographic ROI. */
+  meanLuminanceCdPerSquareMeter: number;
+  spatialFrequencyCyclesPerDegree: number;
+  gaussianEnvelopeSigmaDegrees: number;
+  temporalFrequencyHz: number;
+  eccentricityDegrees: number;
+  /** Neutral carrier fractional amplitude before the Gaussian envelope; not arbitrary ROI extrema. */
+  modulationMichelson: number;
+}
+```

package/docs/api/output-print-detail.md

@@ -0,0 +1,147 @@
+# output/print-detail.ts public contracts
+
+Package **1.2.0**, root API **1.2.0**. [Navigation](../API_REFERENCE.md) · [Developer guide](../DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
+
+## calculatePrintRegionDetail
+
+Calculate one coherent regional fundamental and its print reference scale.
+Acquisition remains unknown; no MTF, noise, compression or perceptual pass is produced.
+
+```ts
+export function calculatePrintRegionDetail(value: PrintRegionDetailInput): CalculationResult<PrintRegionDetailAssessment>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## MAX_PRINT_DETAIL_REGION_SAMPLES
+
+Work bound for one dense ROI, not an actual-device capability claim.
+
+```ts
+MAX_PRINT_DETAIL_REGION_SAMPLES = 65536
+```
+
+## parsePrintRegionDetailInput
+
+Parse/copy bounded, untrusted region/source/target data and existing Print geometry.
+Unknowns, sparse arrays and factual-reference-only numeric samples fail closed.
+
+```ts
+export function parsePrintRegionDetailInput(value: unknown): PrintRegionDetailInput;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## PRINT_REGION_DETAIL_MODEL_VERSION
+
+Metric/protocol identity; independent of the root creator version.
+
+```ts
+PRINT_REGION_DETAIL_MODEL_VERSION = "0.1.0" as const
+```
+
+## PrintDetailRegion
+
+Selected half-open rectangle in the represented oriented retained raster.
+Depth is descriptive, in metres; null explicitly means unknown.
+
+```ts
+export interface PrintDetailRegion {
+  id: string;
+  rect: RasterRect;
+  role: "selected-subject" | "field-diagnostic" | "intentional-defocus";
+  subjectDistanceM: number | null;
+  focusDistanceM: number | null;
+}
+```
+
+## PrintDetailSource
+
+Exact represented source; content hash and decoding are caller assertions.
+
+```ts
+export interface PrintDetailSource {
+  captureId: string;
+  representationId: string;
+  contentSha256: string;
+  raster: RasterDimensions;
+  stage: "native-retained-linear" | "post-resampling-linear" | "post-encoding-decoded-linear";
+  domain: "relative-linear-luminance" | "transfer-encoded-luma" | "unknown";
+  registration: "oriented-retained-unwarped" | "correction-or-warp-unqualified";
+  processing: { id: string; version: string };
+  noiseRealizationId: string | null;
+  evidence: readonly EvidenceProvenance[];
+}
+```
+
+## PrintRegionDetailAssessment
+
+Immutable snapshot with no full-system, artifact, perception or print-quality pass.
+
+```ts
+export interface PrintRegionDetailAssessment {
+  assessmentId: string;
+  engineApiVersion: string;
+  modelVersion: typeof PRINT_REGION_DETAIL_MODEL_VERSION;
+  input: PrintRegionDetailInput;
+  status: "diagnostic-only" | "blocked" | "unsupported";
+  blockers: string[];
+  print: PrintPlan;
+  measurement: PrintSinusoidalMeasurement | null;
+  projection: {
+    fieldPointMm: { x: number; y: number };
+    frequencyCyclesPerMm: { x: number; y: number };
+    physicalPeriodMm: number;
+    angularPeriodAtImageCenterDegrees: number;
+  } | null;
+  assessedRasterMatchesRecommendation: boolean;
+  sourceArtifactVerification: "caller-declared-unverified";
+  assurance: ComposedScientificAssurance;
+  unassessed: readonly ("captured-system-mtf" | "optical-motion-attribution" | "noise" | "aliasing" | "halos" | "compression" | "color" | "perceived-quality" | "printer-substrate")[];
+  overallPrintVerdict: "not-offered";
+}
+```
+
+## PrintRegionDetailInput
+
+Own/reusable scalar relative-linear ROI samples; no RGB/luma conversion is inferred.
+
+```ts
+export interface PrintRegionDetailInput {
+  assessmentId: string;
+  print: PrintPlanInput;
+  source: PrintDetailSource;
+  region: PrintDetailRegion;
+  target: PrintSinusoidalTarget;
+  samples: readonly number[];
+}
+```
+
+## PrintSinusoidalMeasurement
+
+Calculated coefficients for one declared grating; residual is not a noise metric.
+
+```ts
+export interface PrintSinusoidalMeasurement {
+  meanRelativeLuminance: number;
+  fundamentalAmplitudeRelativeLuminance: number;
+  fundamentalModulation: number;
+  declaredGratingTransfer: number;
+  unexplainedResidualRmsRelativeToMean: number;
+}
+```
+
+## PrintSinusoidalTarget
+
+Coherent integer Fourier mode; x right/y down, arbitrary phase at first ROI sample.
+Input modulation is dimensionless, positive and at most one.
+
+```ts
+export interface PrintSinusoidalTarget {
+  id: string;
+  version: string;
+  kind: "coherent-sinusoid";
+  cyclesAcrossRegion: { x: number; y: number };
+  referenceModulation: number;
+}
+```

package/docs/api/output-print-plan.md

@@ -0,0 +1,165 @@
+# output/print-plan.ts public contracts
+
+Package **1.2.0**, root API **1.2.0**. [Navigation](../API_REFERENCE.md) · [Developer guide](../DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
+
+## calculatePrintPlan
+
+Resolve the minimum exact-native-ratio file under declared sampling/lab constraints.
+Angular guidance is approximate as a usage criterion; geometry is calculated.
+No source detail, perceived quality, serializer or resource availability is assessed.
+
+```ts
+export function calculatePrintPlan(value: PrintPlanInput): CalculationResult<PrintPlan>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## calculatePrintSizeLimit
+
+Calculate a conditional size bound. Lab constraints require individual plans;
+this first size-query contract reports them as unsupported rather than ignoring them.
+
+```ts
+export function calculatePrintSizeLimit(value: PrintSizeLimitInput): CalculationResult<PrintSizeLimit>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## parsePrintPlanInput
+
+Validate and copy an untrusted Print request; never infer native authority.
+
+```ts
+export function parsePrintPlanInput(value: unknown): PrintPlanInput;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## PrintedImageSize
+
+Flat printed image area; excludes paper, borders and wraps.
+
+```ts
+export interface PrintedImageSize { width: number; height: number; unit: PrintLength["unit"] }
+```
+
+## PrintLength
+
+Physical length, separate from raster pixels and printer dots.
+
+```ts
+export interface PrintLength { value: number; unit: "mm" | "cm" | "inches" | "m" }
+```
+
+## PrintNativeSource
+
+Declared authoritative geometry, not a preview or resampled pixel count.
+
+```ts
+export type PrintNativeSource =
+  | { kind: "native-retained"; captureId: string; geometry: ResolveCaptureGeometryInput }
+  | { kind: "unavailable"; reason: "missing-native-raster" | "unverified-native-identity" };
+```
+
+## PrintPlan
+
+Finite conditional plan. Null recommendation never authorizes an upscale.
+
+```ts
+export interface PrintPlan {
+  engineApiVersion: string;
+  input: PrintPlanInput;
+  status: "ready" | "insufficient-native-pixels" | "provider-conflict" | "crop-confirmation-required" | "cannot-assess" | "unsupported";
+  nativePixelSufficiency: "sufficient" | "insufficient" | "cannot-assess";
+  reasons: string[];
+  printedImageMm: { width: number; height: number } | null;
+  viewingDistanceMm: number | null;
+  guidance: CalculationResult<{ derivedPixelsPerInch: number; maximumPixelPitchMm: number; maximumArcminutesPerPixel: number | null }> | null;
+  relativeAspectError: number | null;
+  native: PrintRasterSampling | null;
+  minimumSamplingRaster: RasterDimensions | null;
+  recommended: PrintRasterSampling | null;
+  resamplingScale: { x: number; y: number } | null;
+  alternatives: { maximumImageMmAtCurrentDistance: { width: number; height: number }; minimumViewingDistanceMmAtCurrentSize: number | null } | null;
+  capturedDetailAssessment: "unassessed";
+  deliveryAssessment: "unassessed";
+}
+```
+
+## PrintPlanInput
+
+Exact-ratio output policy. Physical aspect tolerance is explicit and reported.
+
+```ts
+export interface PrintPlanInput {
+  source: PrintNativeSource;
+  printedImage: PrintedImageSize;
+  viewingDistance: PrintLength;
+  sampling: PrintSamplingCriterion;
+  fit: { kind: "confirmed-native-aspect"; maximumRelativeAspectError: number };
+  provider?: PrintProviderConstraints;
+}
+```
+
+## PrintProviderConstraints
+
+Caller-supplied lab constraints; no vendor catalog or delivery guarantee.
+
+```ts
+export interface PrintProviderConstraints {
+  minimumRaster?: RasterDimensions;
+  exactRaster?: RasterDimensions;
+  minimumPpi?: number;
+  exactPpi?: number;
+}
+```
+
+## PrintRasterSampling
+
+Per-axis density and angular pitch; angular values are geometry, not acuity.
+
+```ts
+export interface PrintRasterSampling {
+  raster: RasterDimensions;
+  pixelsPerInch: { x: number; y: number };
+  angularPixelPitchArcminutes: { x: number; y: number };
+}
+```
+
+## PrintSamplingCriterion
+
+Explicit angular convention; manual PPI starts a different plan.
+
+```ts
+export type PrintSamplingCriterion =
+  | { kind: "angular-pixel-pitch"; maximumArcminutesPerPixel: number }
+  | { kind: "angular-stroke"; strokeWidthArcminutes: number; samplesPerStroke: number }
+  | { kind: "angular-line-pair"; periodArcminutes: number; samplesPerPeriod: number }
+  | { kind: "manual-ppi"; pixelsPerInch: number };
+```
+
+## PrintSizeLimit
+
+Semantic bounds avoid Infinity sentinels; no-positive-size differs from invalid input.
+
+```ts
+export interface PrintSizeLimit {
+  engineApiVersion: string;
+  status: "finite" | "unbounded" | "no-positive-size" | "cannot-assess" | "unsupported";
+  maximumImageMm: { width: number; height: number } | null;
+  reasons: string[];
+  referencePlan: PrintPlan;
+}
+```
+
+## PrintSizeLimitInput
+
+Size-limit query retains the reference image aspect and criterion.
+Proportional viewing scales the supplied reference distance with both image axes.
+
+```ts
+export interface PrintSizeLimitInput {
+  plan: PrintPlanInput;
+  viewingDistancePolicy: "fixed" | "proportional-to-image-size";
+}
+```