# HARKANA Processing Documentation

Current workflow format: processing-workflow-v2. Historical /v1 resources are
not authoring sources for new workflows. This documents implementation, not
deployment availability; authenticated runtime review is authoritative.

## Canonical resources

- [Manifest](https://docs.harkana.com/docs/processing/v2/manifest.json)
- [Workflow schema](https://docs.harkana.com/docs/processing/v2/processing-workflow.schema.json)
- [Node catalog](https://docs.harkana.com/docs/processing/v2/processing-nodes.json)
- [Complete workflow examples](https://docs.harkana.com/docs/processing/v2/processing-workflows.json)
- [Authoring contract](https://docs.harkana.com/docs/processing/v2/processing-authoring.json)
- [Graph patterns](https://docs.harkana.com/docs/processing/v2/processing-workflow-patterns.json)
- [Project-bound postprocessing package schema](https://docs.harkana.com/docs/processing/v2/processing-postprocessing-workflow-package.schema.json)
- [Upload review schemas](https://docs.harkana.com/docs/processing/v2/processing-upload.schema.json)
- [Processing contract](https://docs.harkana.com/docs/processing/v2/processing-contract.md)
- [File formats](https://docs.harkana.com/docs/processing/v2/processing-data-formats.json)
- [Billing policy](https://docs.harkana.com/docs/processing/v2/processing-token-billing.json)


## Workflow generation behavior

When asked to create, build, generate or provide a HARKANA workflow, return
complete functional JSON, not merely a conceptual graph or pseudocode, unless
the user explicitly asks only for an explanation. Provide a downloadable JSON
artifact where your tools allow it, plus a fenced json block. Do not claim to
have fetched or validated a file you could not retrieve.

1. Fetch the manifest, then its workflow schema and node catalog; consult examples.
2. Look up every node's exact nodeType, nodeVersion, port names, parameter schema
   and inputRequirements, including each port's bindingSchema where supplied.
   Do not invent unsupported nodes, ports, or parameters.
3. Use actual reviewed variable/dimension/coordinate names. A role assignment is
   not calibration. Index coordinates are valid only where the node permits them.
4. Respect required fields, types, enums, numeric bounds and conditional rules.
   Use authoring.parameters, including nested defaults and missingValueBehavior;
   ask only for unresolved scientific/execution choices. Schema defaults are
   annotations; runtime normalization applies the effective defaults.
5. Generate unique node IDs and descriptive display/output names. Omit generated
   output IDs and stale workflow hashes. Terminate every requested saved branch
   with analysis-output; branch before processing to keep original and derivative.
6. Include views for requested visible results. Empty views/analyses mean save-only.
   Resolve output member names, variables and relationships from resultSchema;
   do not treat Gaussian parameter fields or peak rows as spectral curves.
7. For postprocessing from a reviewed project input description, copy exact used
   sourceBindings into a complete project-postprocessing-workflow-package-v1,
   alongside projectID and workflow. Never request manual binding of supplied
   aliases or invent selectors. The inner graph's phase is postprocessing.
8. Validate the JSON schema AND graph semantics (IDs, cardinality, ports, bindings,
   topology). Runtime source/science checks are separate. Do not claim runtime
   scientific validity from schema validation alone.
9. Return complete JSON without placeholders or structural fields left for the
   user to add. If required facts cannot be retrieved, name the unresolved field
   or node precisely, rather than returning illustrative JSON as import-ready.

Machine-readable workflow/schema/catalog metadata overrides prose. A valid graph
is not a submission request: upload source selections and postprocessing context
authorization are reviewed separately. Private project input descriptions are
never part of the public documentation. Importing a package does not start a job.
The package/import addition requires an API release and client adoption; public
documentation publication alone does not make that route available.

## GP binding rules

GP edges use modeledCoordinates (required on dataset) and optional
groupByCoordinates (dataset only). Omit dimensions, coordinates and
dimensionParameters from GP edges; do not copy another operation's axis binding.
Names in modeledCoordinates identify actual named coordinates, not dimension
roles. For example, {"variable":"signal","modeledCoordinates":["timeAxis"]}
is valid only if timeAxis exists on the selected signal. The optional
targetCoordinates port can reuse source coordinate names when its list is omitted.
Keep output-view coordinates separate; a time-trace view needs its reviewed time
coordinate to display calibrated values. Each output-view coordinate reference
must use the same memberID as the signal (for GP mean views, mean, not dataset).
In postprocessing, omit memberID on outgoing imported-source edges because the
context already pins the member. inputID must match the reviewed sourceBindings
alias; it does not itself bind an output. Do not invent project selectors or
substitute an output ID for authority.

## Complete branching upload example

This portable graph preserves the source and a 3x3 spatial mean. Upload review
must resolve its spectral/y/x authoring intent against actual source identifiers.
It intentionally prepares spectrum views; consult the examples for Layers,
MIP, HSV-MIP, UMAP, PCA and time-series waterfall requests.

```json
{
  "authoring": {
    "generatedFeatures": {
      "rawOutput": [
        "spectrum"
      ],
      "smoothedOutput": [
        "spectrum"
      ]
    },
    "generatedRequests": {},
    "inputs": {
      "uploaded": {
        "dimensions": {
          "spectral": "spectral",
          "x": "x",
          "y": "y"
        },
        "variable": "signal"
      }
    },
    "outputProfiles": {
      "rawOutput": "exploration",
      "smoothedOutput": "exploration"
    },
    "resolvedInputs": {},
    "version": "workflow-authoring-v1"
  },
  "description": "Save uploaded and spatially smoothed datasets.",
  "edges": [
    {
      "binding": {
        "coordinates": {},
        "dimensionParameters": {
          "x": {
            "windowSize": 3
          },
          "y": {
            "windowSize": 3
          }
        },
        "dimensions": {
          "axes": [
            "y",
            "x"
          ]
        },
        "groupByCoordinates": [],
        "modeledCoordinates": [],
        "variable": "signal"
      },
      "fromNodeID": "input",
      "fromOutput": "dataset",
      "toInput": "dataset",
      "toNodeID": "spatialAverage"
    },
    {
      "binding": {
        "coordinates": {},
        "dimensionParameters": {},
        "dimensions": {},
        "groupByCoordinates": [],
        "modeledCoordinates": []
      },
      "fromNodeID": "input",
      "fromOutput": "dataset",
      "toInput": "primary",
      "toNodeID": "rawOutput"
    },
    {
      "binding": {
        "coordinates": {},
        "dimensionParameters": {},
        "dimensions": {},
        "groupByCoordinates": [],
        "modeledCoordinates": []
      },
      "fromNodeID": "spatialAverage",
      "fromOutput": "result",
      "toInput": "primary",
      "toNodeID": "smoothedOutput"
    }
  ],
  "friendlyName": "Save uploaded and spatially smoothed datasets",
  "nodes": [
    {
      "displayName": "Uploaded dataset",
      "nodeID": "input",
      "nodeType": "dataset-input",
      "nodeVersion": "dataset-input-v2",
      "parameters": {
        "inputID": "uploaded"
      }
    },
    {
      "displayName": "3x3 spatial mean",
      "nodeID": "spatialAverage",
      "nodeType": "local-mean",
      "nodeVersion": "local-mean-v2",
      "parameters": {}
    },
    {
      "nodeID": "rawOutput",
      "nodeType": "analysis-output",
      "nodeVersion": "analysis-output-v2",
      "parameters": {
        "analyses": [],
        "friendlyName": "Uploaded dataset",
        "save": {
          "members": "all"
        },
        "views": [
          {
            "adapterID": "line",
            "adapterVersion": "line-v1",
            "browse": {},
            "coordinates": {},
            "displayDimensions": [
              "spectral"
            ],
            "featureID": "spectrum",
            "fixedIndices": {},
            "label": "Spectrum",
            "relationshipIDs": [],
            "selectionDimensions": [
              "y",
              "x"
            ],
            "shortLabel": "Spectrum",
            "signal": {
              "memberID": "dataset",
              "variable": "signal"
            },
            "spatialDimensions": []
          }
        ]
      }
    },
    {
      "nodeID": "smoothedOutput",
      "nodeType": "analysis-output",
      "nodeVersion": "analysis-output-v2",
      "parameters": {
        "analyses": [],
        "friendlyName": "Spatially smoothed dataset",
        "save": {
          "members": "all"
        },
        "views": [
          {
            "adapterID": "line",
            "adapterVersion": "line-v1",
            "browse": {},
            "coordinates": {},
            "displayDimensions": [
              "spectral"
            ],
            "featureID": "spectrum",
            "fixedIndices": {},
            "label": "Spectrum",
            "relationshipIDs": [],
            "selectionDimensions": [
              "y",
              "x"
            ],
            "shortLabel": "Spectrum",
            "signal": {
              "memberID": "dataset",
              "variable": "signal"
            },
            "spatialDimensions": []
          }
        ]
      }
    }
  ],
  "phase": "upload",
  "version": "processing-workflow-v2",
  "workflowHash": "3ca4469d6fb799fd2a9f251dfb752ecf603c02caebc33d608e023c540bd646f4"
}
```