# HARKANA Processing Contract

## Authority and availability

Current workflow serialization is processing-workflow-v2. The workflow schema,
node catalog and parameter schemas are authoritative over prose. Historical v1
resources must not be used to generate new workflows. This publication describes
the backend implementation, not a certification that every environment has
enabled every route. Authenticated runtime review remains mandatory. In
particular, the project-bound postprocessing package/import addition is locally
tested and requires an API release and client adoption; publication alone does
not deploy it. No public documentation grants project access or execution rights.

## Dataset, dimensions and coordinates

A Dataset contains named dimensions, variables and coordinates. Variables have
their own ordered dimensions; there is no mandatory LXY or four-dimensional
array layout. Spectral, temporal and spatial roles annotate dimensions, not file
formats, project types or a required rank. Single spectra, spectral time series,
spatial hyperspectral datasets and hyperspectral time series use this same model.
Choose actual native variable/dimension names exposed by source inspection.
Do not add graph-level dataType or shapeKind. A viewing profile does not define
the Dataset's scientific shape and different outputs can have different views.

Retained dimensions receive named unitless index coordinates when admitted under
the current index-coordinate policy. Native coordinates are preserved as well.
Use returned coordinate names and generatedIndex/coordinateMode metadata; do not
guess names. Selecting a spectral or time role does not create physical calibration.
Missing units remain null. A coordinate may be physical even with unknown units.
Operations requiring physical coordinates do not accept indices as substitutes.
Omitted singleton dimensions can be removed during explicit source selection;
an omitted non-singleton dimension requires an explicit fixed index. Retained
singleton dimensions remain present. Stored older results are not silently upgraded.

## Upload review and bindings

Workflow nodes name logical input aliases with parameters.inputID. Upload
sourceBindings are separate from the workflow and map each used alias to
{sourceID, selection}. SourceSelection.dimensionRoles maps native dimension IDs
to roles; bindingSelections.dimensions maps roles to native dimension IDs.
Those opposite directions must not be confused. bindingSelections.coordinates
associates a dimension with an actual coordinate name; null requests index
display and is not physical calibration. Selecting a coordinate array and
binding it to an operation are distinct decisions.

Canonical authoring intents in workflow.authoring let upload review compile
portable variable/dimension names against reviewed source selections. Only
declared generatedFeatures may be conditioned; literal authored views remain
requirements. Always use the returned workflow, sourceBindings and
bindingSelections for the next review, repair and submission. Do not preserve
nonexistent template coordinates such as shift, or substitute a scientifically
different coordinate just because it is the only one available. Native NetCDF
coordinate discovery and explicit coordinate binding are documented in
processing-data-formats.json. Native identifiers are consistent across source
inspection and review; clients must not hardcode TIFF or OIR axis aliases.

Structural validity is not scientific compatibility. Inspect bindingErrors,
axisEvidence, outputReview and canSubmit, not only a single compatible flag.
Scientific checks can be deferred to execution; a known binding error blocks
submission. Spectrum sampling and axis-only preview are separate capabilities.
Large data may have no bounded spectrum preview while remaining submit-ready.
Read previewAvailability and structured previewWarnings: unavailable optional
sampling is not a failed upload and must not be presented as proof of an invalid
workflow. Axis-only preview reads coordinates rather than the full signal.

## Dataset-wide axis repair

Use backend-advertised opaque targets in repair-preview. Repairs act at selected
uploaded/reference sources before their downstream branches, not arbitrary
scientific nodes. Insertion assigns a reviewed donor coordinate and preserves
measurement sample order. Reverse spectral axis reverses assigned coordinate
values without reversing the measurement signal. Flip axis and signal reverses
both, preserving coordinate-signal pairings; its target kind is
flip-spectral-axis-and-signal-node. For inserted coordinates the combined flip
occurs after assignment. Donor values and unrelated aliases are not changed.
Do not construct a replacement graph from a friendly label. Use fresh returned
review and preview targets. Undo restores the prior graph/bindings and reviews
again; stale source evidence or unsafe replacement is a conflict, not permission
to silently delete shared dependencies. Result-axis and result-spectrum previews
evaluate supported repair chains and must not substitute an unrepaired source.

## Operations and output materialization

Catalog nodeType/nodeVersion and port name are serialization selectors. label
and shortLabel are display text, not selectors. Node displayName and output
friendlyName are user-facing. Node IDs must be unique within a graph. Omit
backend-allocated outputID and a stale workflowHash when authoring new graphs.
Nodes bind operated dimensions explicitly. local-mean supports one or two axes;
spatial averaging uses two independently configured odd window widths. GP uses
modeledCoordinates and optional groupByCoordinates instead of axis bindings.
On GP edges, omit dimensions, coordinates and dimensionParameters (empty
objects are permitted; nonempty objects are not). The dataset port requires
modeledCoordinates; targetCoordinates may omit them to reuse source coordinate
names and does not accept groupByCoordinates. Use the per-port bindingSchema
in the catalog. View coordinates are a separate output-view setting: do not
remove them merely because the processing edge uses GP syntax. GP output members
retain the bound signal variable name; their coordinates come from the target
Dataset, or the source when there is no target. View coordinate keys are
dimension names; references must name coordinates in the viewed member and
specify the same memberID as the view signal, for example mean, not dataset.
Independent fitting is default; shared-hyperparameters 1D fitting retains
separate curves, not one pooled prediction. Exact eligibility and resource
requirements are in the node catalog. Neural model internals are not public.

Every requested saved result terminates in its own analysis-output node. Fan-out
can preserve an uploaded Dataset while another branch processes it. save.members
is all; views and analyses describe additional prepared access. Empty views and
analyses save data but prepare no plots. Requested visible results need explicit
views or documented generated exploration intents. New optional adapters do not
retroactively add views to an existing graph. Saved values remain distinct from
preparation state; failed preparation does not erase a saved Dataset.

line displays one dimension; grid displays two, not necessarily spatial axes.
Specify all other dimensions as browse, fixedIndices or selectionDimensions;
do not silently choose the first time frame. Spectral time series support a
time-versus-spectral waterfall, spectra selected over time and time traces selected
over spectral samples. Both return their displayed axis in full. Generic metadata
does not require frontend-specific 3D plots. Browsing-only authored views remain valid.
MIP, HSV-MIP and UMAP image projections can advertise a same-output spectrumQuery
link; use that link for ROI spectra rather than inferring a relationship by name.
Waterfalls advertise lineQueries for compatible prepared Spectrum and Time trace
companions. Each link includes targetFeatureID, targetFeatureVersion and an explicit
selectionPolicy. Submit both target selectors together, the waterfall feature
ID/version and both image dimension bounds to feature-queries. Spectrum selects
time samples and returns the full spectral axis; Time trace selects spectral
samples and returns the full time axis. The other rectangle extent is validated
but does not crop the returned axis. The existing spectrumQuery remains the
preferred/unique default when target selectors are omitted. Request
mean and quantiles through the existing statistics object. Point selections are
one-sample aggregates. Both points and rectangles require statistics.mean=true.
Omit range; waterfall-origin queries always return the full
advertised line axis. resolvedFeature names the pinned companion. Saved waterfall ROI
projection is not yet supported. Literal browse-only spectrum views remain valid
but cannot provide temporal region statistics without explicit re-preparation.
Neural medians and configured predictive intervals are separate saved members
with explicit relationships; requested interval IDs must exist in the result.
An authored line view with omitted relationshipIDs or [] prepares no bands.
At query time, omitted relationshipIDs selects all already prepared bands; []
suppresses them. Aggregate native interval bounds require statistics.meanBounds=true;
they are averages of native bounds, not new uncertainty estimates for an aggregate.
Sample quantiles are a separate sample-spread band. GP Gaussian bands use compact
sigma captions, such as Latent uncertainty - 1 sigma. Local mixture bands describe
sigma-equivalent coverage instead. Relationship selectors and probabilities remain
authoritative; never infer uncertainty from a member name or sample-quantile band.

PCA/RPCA are paired analysis-output analyses, not separate graph nodes. Each fit
owns scores and loadings with distinct feature IDs and output analysisGroups.
componentSelection uses count or a cumulative variance target. Frontend owns
visualization choices for the advertised analysis; the backend owns the numerical
result and access contract. RPCA is not requested by maintained default examples.
UMAP is stochastic and is not replaced by a PCA fallback on failure.
Only READY advertised features may be fetched, using their pinned versions.
Large ROI statistics and image windows use bounded access; a preview limit is
not a project size limit. All integer ranges are half-open unless a node's
scientific parameter explicitly defines an inclusive physical interval.

## Postprocessing, reusable graphs and history

Selected saved members are legitimate independent workflow inputs. Multiple
aliases may bind different outputs, retained result versions or members. A
downloaded input description contains metadata and exact sourceBindings for
the selected aliases, not all project outputs and not credentials. Treat it as
private user data. When authoring from that description, return a complete
project-postprocessing-workflow-package-v2 containing projectID, a postprocessing
workflow and sourceBindings for used aliases only. Do not ask the user to bind
an alias already described. Do not put those fields inside the portable graph.
inputID is a logical alias matching a sourceBindings key, not an output lookup.
Bindings carry bindingKind: saved-result with exact projectID/outputID/resultVersion/memberID,
or reference-source with exact projectID/sourceID/sourceRevision. A canonical
reference exposes one standalone dataset, not a result bundle or an inferred
member. Reference presence alone does not request an output or visualization.
An output ID used as an alias has no automatic binding authority. Selected source
members are already resolved by the context: omit memberID on outgoing source
edges. Explicit memberID remains useful on edges selecting intermediate surfaces.
The original bundle inventory and relationships are informational. Each selected
source member becomes a standalone Dataset named dataset with no inherited
bundle relationships; bind additional members through additional aliases.
Null primary variables/members stay null; select actual variables explicitly.
Scalar parameter fields and empty peak rows can be saved, but do not invent
line/grid views where a nonempty displayed dimension does not exist.
POST /projects/{projectID}/postprocessing/import authenticates current access,
restores a private context and returns a preview without starting or charging a
job. Normal review, cost estimate and submission remain required. Unknown or
inaccessible retained versions fail; do not switch to latest. Metadata-resolvable
view errors block submission; unresolved transformed output shapes remain
explicit deferred checks. Import does not infer requested plots from save-only.

Reusable templates/profiles store portable graphs, not private project packages.
Profiles retain authorized reference selections and accepted projects own their
reference copies. Later profile deletion does not change accepted scientific
inputs. Combining upload and postprocessing for reuse uses processing-recipe-v1
stages and saved-member dependencies, not a flattened graph.
External reference-source bindings on retained recipe branches are unsupported;
no output is fabricated to represent them. Recipe execution is capability-gated
pending v2 runtime migration; standalone reference-bearing profiles remain the
reuse path. Canonical source integration is locally implemented and tested,
not certified deployed or enabled by these documentation artifacts.
Exact accepted
graphs and staged recipes are workflow history; opening them creates a new
draft, not an edit to the historical execution. Missing historical graphs are
reported explicitly. Project-read permission does not imply permission to
execute postprocessing. There is no lifetime 24-output cap; discovery is paginated
with opaque continuation cursors. Per-request/transaction limits still apply.

## Project operations and billing

Archives, copies, metadata and Zenodo export are separate project operations,
not scientific output nodes. Whole-project Zenodo export excludes chats;
feature selection is a distinct export mode. Read authorization and operation
availability are verified at runtime. Storage, compute and delivery accounting
remain independent of scientific success. Consult processing-token-billing.json
and the authenticated effective pricing response; documentation is not a quote.