Project

Author and operate a cloud-native Python batch job

A production-shaped project blueprint grounded in Honua's AWS Batch custom-code contract; Studio authoring and SDK submission remain explicit product gaps.

Server contract first

AWS Batch custom-code job

contract-only

Fixture endpoint: No runnable endpoint admitted
Service manifest key: Not admitted
Evidence: unavailable at honua-server:trunk
Server version: ADR-0063 and current CustomCodeJobContract
Owner: honua-server execution platform
Support: Server contract; no admitted Studio workflow

Authentication

The server mints a job-bound token from declared scope and owner snapshot; arbitrary user-supplied secrets are not an admitted submission surface.

Cancellation

Use the server job cancellation surface when a real registered task exists; exact custom-code cancellation receipt remains unpinned.

Errors

Fail closed on repository policy, unsigned/unapproved commit, invalid runtime/entrypoint/manifest/scope, workload routing, token minting, timeout, or artifact publication failure.

Server capability IDs

Geoprocessing Task Execution (process.geoprocessing)

contract-only

geoservices-gp-custom-code

POST /rest/services/{serviceId}/GPServer/{taskName}/submitJob

This is a server contract shape, not a runnable sample. No concrete service manifest/fixture is admitted, so the gallery must not offer Run.

{
  "method": "POST",
  "endpoint": "/rest/services/{serviceId}/GPServer/{taskName}/submitJob",
  "payload": {
    "customcode.runtime": "python",
    "customcode.repo_url": "https://github.com/example/approved-job.git",
    "customcode.git_ref": "<full-40-character-commit-sha>",
    "customcode.entrypoint": "job.main:run",
    "customcode.deps_manifest": "requirements.lock",
    "customcode.params_json": "<bounded-json>",
    "customcode.declared_scope": "<approved-scope>"
  }
}

{
  "jobId": "<server-assigned>",
  "jobStatus": "esriJobSubmitted",
  "outputPrefix": "server-assigned S3 prefix"
}

Normalized semantics

{
  "runtimeProfile": "custom-code",
  "runtime": "python",
  "source": "allowlisted repository at full commit SHA",
  "entrypoint": "module.path:function",
  "dependencies": "relative locked manifest",
  "identity": "server-minted scoped job token",
  "outputs": "server-assigned S3 prefix",
  "timeout": "server policy, 1 minute to 24 hours"
}

{
  "state": "planned integration",
  "artifacts": "declared through GpContext output sink",
  "provenance": [
    "source commit",
    "runtime image",
    "job id",
    "owner snapshot",
    "declared scope",
    "output prefix"
  ]
}

Semantic assertionDo not admit this project as runnable until a committed service manifest, pinned Batch fixture, lifecycle receipt, artifact digest, cleanup receipt, and Studio/CLI/API evidence all exist.

Evidence

honua-server ADR-0063 accepted custom-code architecture
honua-server CustomCodeJobContract
honua-server docs/customcode/raster-gp-pattern.md
sanctioned docker/worker-customcode-python image

Limits and blockers

AWS Batch is the only admitted untrusted custom-code backend.
No current Studio Python editor/runtime/dependency/publish surface was found.
No JS, Python, .NET, or Honua CLI custom-code submission wrapper was found.
STAC, COG, and GeoParquet input/output bindings, per-job CPU/memory/retry/idempotency, log streaming, and artifact TTL are not admitted public submission fields.

Server references

Unpinned upstream reference withheld
Unpinned upstream reference withheld

Governed project blueprint

Architecture and admission gaps come before code.

This is not a runnable application. It records the current server contract, ordered product gaps, approval boundaries, and the evidence required before runtime admission.

Contract source: jobs/cloud-native-python-job.json
Runtime: Not admitted
Evidence: unavailable

Open governed project contract ↗

Ordered job walkthrough

Complete the lifecycle deliberately.

gapCreate the Python job in Studio
No current Studio action exists; start from a reviewed repository outside Studio.
Expected: Planned: a searchable Python project with no embedded credentials.
contract-onlyDeclare runtime and dependencies
Set runtime=python, module:function entrypoint, and a relative locked dependency manifest at a full commit SHA.
Expected: A policy-reviewable immutable source descriptor.
contract-onlyPin inputs and outputs
Use staged inputs and the server-assigned S3 output prefix through GpContext.
Expected: No caller-chosen output path; STAC/COG/GeoParquet bindings remain unclaimed until implemented.
contract-onlyConfigure identity and secrets
Declare the minimum scope; let the server mint HONUA_JOB_TOKEN and HONUA_BASE_URL.
Expected: A job-bound identity with no arbitrary secret material in params.
gapSet resource and retry bounds
Use the server timeout policy; do not claim per-job CPU, memory, retry, or idempotency fields.
Expected: Planned: explicit bounded submission fields and policy receipt.
contract-onlyBuild and package
Pin an allowlisted repository commit and run only in the sanctioned worker-customcode-python image selected by the workload registry.
Expected: A reproducible source/image identity; no caller-provided image.
gapRegister and publish the process
No admitted Studio or public SDK registration action exists.
Expected: Planned: versioned process definition and publish receipt.
contract-onlySubmit the job
Use the custom-code metadata contract through a registered GPServer task only after policy approval.
Expected: A server-assigned job id and Batch execution identity.
gapObserve logs and progress
Poll the existing job status where available; do not claim a Studio log stream.
Expected: Planned: bounded redacted logs and monotonic progress receipt.
contract-onlyCancel
Require explicit operator approval and use the registered task's cancellation surface.
Expected: A terminal cancellation state tied to the approval and job id.
contract-onlyCollect artifacts and provenance
Declare artifacts through context.output.add_artifact under the server output prefix.
Expected: Artifact keys and digests tied to source commit, image, and job id.
gapCleanup and TTL
No public artifact TTL/cleanup contract is admitted.
Expected: Planned: explicit retention policy plus deletion receipt.
gapCapture a CI fixture receipt
Add a pinned Batch fixture only after the complete lifecycle is deployable.
Expected: A deterministic non-secret receipt that gates gallery admission.

Final assertionDo not admit this project as runnable until a committed service manifest, pinned Batch fixture, lifecycle receipt, artifact digest, cleanup receipt, and Studio/CLI/API evidence all exist.

Equivalent client surfaces

Choose a language without changing the job.

No public symbol

Unavailable - no pseudocode shown.

The JS OGC/GP runners can operate registered processes but do not author, package, register, or submit the custom-code metadata contract.

Exact reference matrix

Raw contract and public symbols

Surface	Operation or symbol	Package and version	Ownership and behavior
Raw HTTPcontract-only	`POST /rest/services/{serviceId}/GPServer/{taskName}/submitJob` Unpinned upstream link withheld	Honua Server min current trunk contract - Contract-only	honua-server execution platform Auth: Caller auth plus server-minted job-bound token. Cancel: Job cancellation only after a registered task exists; fixture receipt missing. Errors: Policy and workload failures must fail closed.
CLIgap	Gap: No create/package/register/publish/submit/logs/cancel/artifacts/cleanup CLI commands or --help references exist.	Not applicable min n/a - Unavailable	SDK/CLI Auth: Not applicable. Cancel: Not applicable. Errors: Not applicable.
JavaScriptgap	Gap: The JS OGC/GP runners can operate registered processes but do not author, package, register, or submit the custom-code metadata contract.	Not applicable min n/a - Unavailable	honua-sdk-js Auth: Not applicable. Cancel: Not applicable. Errors: Not applicable.
Pythongap	Gap: HonuaGeoprocessing operates registered OGC processes; it exposes no custom-code repository/runtime/dependency/scope submission API and executes no untrusted code locally.	Not applicable min n/a - Unavailable	honua-sdk-python Auth: Not applicable. Cancel: Not applicable. Errors: Not applicable.
.NETgap	Gap: IHonuaProcessesClient operates registered processes; no custom-code authoring, package, registration, or typed metadata submission surface is present.	Not applicable min n/a - Unavailable	honua-sdk-dotnet Auth: Not applicable. Cancel: Not applicable. Errors: Not applicable.

Console configuration

Planned UI, raw contract only

Route: Not implemented
Required role: Not defined
Visual receipt: Not captured

{
  "contract": "The raw customcode.* parameters and server-set environment above are the only current searchable/copyable configuration.",
  "plannedRoute": "/studio/processes/{processId}/versions/{version}/runtime"
}

No screenshot published.

Planned Studio Python batch process configuration showing immutable source, runtime, identity, resource bounds, and publish review. This remains planned until a real route and golden receipt exist.

Optional AI context - planned

No executable Honua AI surface admitted

Allowed drafting tasks

explain the custom-code contract
draft a dependency manifest
draft bounded configuration
plan validation steps

Context inputs

capability manifest
CustomCodeJobContract
repository policy
process schema
runtime image metadata

Provider and data boundary

No real Honua AI custom-code authoring surface is admitted. A future provider/model must be explicitly configured with repository and data-boundary policy.

Injection and privacy boundary

Repository content, manifests, process metadata, and asset metadata are untrusted context; never expose credentials, tokens, signed URLs, or unrestricted source files.

Deterministic validation

Generated scaffolds/configuration must pass schema, repository-policy, dependency-lock, scope, resource-bound, and fixture checks before an approval can be requested.

Approval boundary

AI may draft only. Build, register, publish, submit, cancel, delete, artifact access, and cleanup require explicit human approval and a single-use execution receipt.

Prohibited autonomous actions

execute without required human approval
build or publish code
submit, cancel, or delete jobs
change service identity or secrets
read unrestricted repository or object-store data

Fallback and provenance

Follow the raw contract and manual repository review; the project remains non-runnable until the product surfaces exist.

Future receipts must bind provider/model, prompt/config digests, source commit, dependency lock, runtime image, approvals, job id, artifacts, and cleanup outcome without storing raw secrets or prompts.