Install, register and publish

Role: Model owner or co-admin, coordinating with a connector owner. Prerequisites: Local scientific tests pass; an execution host and approved release root exist; your account has a compute grant for the chosen context. Replace example origins, IDs and paths with your site’s values.

Start with the offline model examples if you need a tested project first. The fixture map distinguishes the scalar, file and collection model IDs and their installed roots. Keep the selected model ID, entrypoint and release path together throughout this procedure.

Agree on installation and execution

The connector owner configures hosts, execution accounts, SSH, launchers, roots and connector credentials. Authors supply scientific software, wrapper, dependencies, installed datasets and, for Slurm, a batch script. OS installation permission and Enumeray compute permission are separate.

From your editable project, select a granted context:

enumeray auth configure https://enumeray.example.org
enumeray auth login
enumeray auth whoami
enumeray connector grant available

Inspect the context’s driver, execution location and disclosure. Agree on an absolute release path under an approved root. Edit execution.context_id and execution.release_path directly in publication.json. There is no additional site file or manifest-generation step. Contexts own direct/SSH access; the same author format serves every supported path.

Complete a process publication

Use the complete process publication, whose execution section is:

{
  "context_id": "lab-cpu",
  "release_path": "/opt/enumeray/models/example/r1",
  "entrypoint": ["wrapper.py", "execute"]
}

This is the execution object, not a complete publication. The executable is relative to the installed release and remaining argv entries are fixed arguments. Omitted environment means {}. The context supplies the driver; there is no duplicate author driver field.

On the execution host, from the tested project, create a new immutable release. The connector owner must prepare the parent directory and access first:

RELEASE_DIR=/opt/enumeray/models/example/r1
mkdir "$RELEASE_DIR"
cp -R . "$RELEASE_DIR/"
chmod a+rx "$RELEASE_DIR/wrapper.py"
python3 -m unittest discover -s "$RELEASE_DIR" -p 'test_starter.py'
chmod -R a-w "$RELEASE_DIR"

Copy required binaries, dependencies and datasets too. Use site-specific permissions for private resources. Verify parent traversal and read/execute access as the actual execution account. The starter uses #!/usr/bin/env python3; ensure the intended interpreter is available there. Resolve installed resources relative to the release; put writable native configuration, scratch and results in the separate job workspace. Use a new release directory for changed installed content.

Keep release paths and declared executable/batch paths outside work_root/UUID and descendants for every registered context. Registration rejects this reserved run namespace with reserved_run_installation_path. A separate work_root/releases/r1 can be allowed by ordinary root rules. Historical publication retries retain their original records; cleanup protects known overlapping historical releases and observed aliases.

Complete a Slurm publication

The complete Slurm publication changes the selected context and adds execution.slurm_script: "model.sbatch". Edit this batch file before installing/freezing the release:

#!/bin/bash
#SBATCH --nodes=1
#SBATCH --ntasks=1
#SBATCH --cpus-per-task=1
#SBATCH --mem=128M
#SBATCH --time=00:01:00

set -eu
# Add the site's account, partition and cluster directives above.
# Load modules or activate the scientific runtime here.
exec "$1" local-worker --directory "$2"

The connector passes its worker executable as $1 and the job directory as $2. Keep the worker in the foreground; it launches the registered wrapper inside the allocation. Choose account, partition, resources and runtime/container/MPI setup for the actual model and site. Exported batch setup and allocation variables reach the wrapper. Dependencies, installed resources and workspace paths must be accessible from compute nodes. Local tests do not submit scheduler jobs. See the batch-file contract and the illustrative EUHFORIA layout.

Installation environment entries cannot override HOME, PATH, PYTHONDONTWRITEBYTECODE, or the case-sensitive prefixes SLURM_, PMI_, PMIX_, LD_, DYLD_. Empty/identical overrides also fail; diagnostics show the key without its value. Put scheduler/runtime setup in the batch file. The runner supplies workspace HOME and PYTHONDONTWRITEBYTECODE=1.

Validate, create the catalogue model and save a release

python3 -m unittest discover -s . -p 'test_starter.py'
enumeray model validate --file publication.json
enumeray model create example --file publication.json
enumeray model release init example --file publication.json --directory release-r1
enumeray model release resume release-r1
enumeray model release status release-r1

Create the catalogue model only once. --file imports the declaration’s model ID/name/description; it does not register execution or update an existing model’s metadata. Manual model create example --name 'Example model' also remains available.

Validation runs offline, requires complete context/path settings and assigns no candidate ID. Initialization requires a complete publication, checks model identity/authority and freezes the editable source, normalized machine request, newly assigned candidate ID and observed current publication. It does not register. resume registers that exact saved candidate and waits for connector readiness. Run it again after interruption or an uncertain reply; it never activates or refreshes an activation guard. A new initialization into a new directory explicitly requests a new candidate. Source edits after initialization do not change the saved candidate.

The release directory is private, bound to this API/account and exclusively locked while a command runs. Preserve all files, including release.json, publication.json, state.json and release.lock; credentials are not saved. Its publication.json is generated machine evidence with the assigned ID, not another author-maintained source. Do not feed machine evidence back into the editable author parser.

If release init itself was interrupted before it wrote state.json, and no resume or registration was ever attempted, preserve that partial directory and explicitly initialize a new directory from the original editable publication. If that source is unavailable, its frozen author value is source.publication in release.json for a source.kind of publication; save that value as a new author file before initialization. This creates a new candidate ID for an unused initialization. Missing files alone do not prove registration never started. If resume may have run, preserve the original candidate and evidence, recover its original checkpoints or inspect/adopt that exact candidate with --candidate. Never create a fresh ID merely to resolve uncertain registration.

resume --interval 2 --deadline 3600 uses positive seconds. Deadline exit 5 and Ctrl+C exit 130 retain the operation. Installation/authority blockers exit 1 and show the next responsible action. Inspect context/grant, installed paths and validation messages with the connector owner. Changed immutable settings need a new candidate and directory. Preflight uses me:read, models:read, models:manage and connectors:read; the captured grant cannot be replaced inside an existing candidate.

Check	Evidence
Local executable tests	Scientific values and file bytes asserted by your tests
model validate	Supported scientific contract, examples and supplied execution settings
Release initialization	Complete source frozen with one candidate identity and current authority observations
Registration on resume	Model administration, active compute grant and context policy
Connector readiness	Observed executable/batch-file digests, execution identity and backend access
Submitted candidate trial	Installed execution path produces the result you inspect

Readiness does not execute every example or attest every dependency/dataset. A connector’s desired configuration is bounded to 1,024 required publications and 2 MiB; retained installation cache is bounded to 4 MiB. Capacity rejection preserves configuration. Coordinate retirement of unused entries with the connector owner.

Registration reuses an installation key for identical model/context, physical settings and scientific installation identities. Changed settings/identities get a new key; compatible schema/example edits may reuse installed content. A permanently revoked installation cannot be reused, even after grant reissue.

Activate and exercise the installed model

Before activation, use the full Candidate ID displayed by model release status release-r1 as PUBLICATION_ID, or adapt its displayed trial-init command. Keep the release and trial in separate private directories:

PUBLICATION_ID='REPLACE_WITH_FULL_CANDIDATE_ID_FROM_RELEASE_STATUS'
cat > trial-inputs.json <<'JSON'
{"value":2}
JSON
enumeray analysis init example --candidate "$PUBLICATION_ID" \
  --inputs trial-inputs.json --directory trial-r1
# Review the exact installation, execution location and full disclosure.
enumeray analysis submit trial-r1
enumeray analysis wait trial-r1 --check-outcome
enumeray analysis status trial-r1
enumeray analysis logs trial-r1
enumeray analysis collect trial-r1
enumeray model release status release-r1

Initialization displays and saves the exact candidate installation, readiness, execution location, scientific-data access disclosure, captured grant and any named delegation. Review them before explicitly submitting. This also works for a first ready candidate when the model has no current publication. Use --example NAME instead of --inputs FILE for a named candidate example. Bind ordinary files with --file SLOT=PATH and collections with --collection SLOT=DIR or --collection-manifest SLOT=MANIFEST.json, using the candidate’s declarations and any required --media-type SLOT=TYPE. Completed artifact and collection references can also be supplied in the input JSON.

The caller must still administer the model, retain model execution access and own the candidate’s captured compute grant or an exact active named handoff from its holder. Scoped tokens need models:read, models:manage, runs:create and me:read for initialization/submission; uploads and inspection need the ordinary run/artifact scopes. Another administrator’s grant cannot be substituted.

Trials use ordinary queue/capacity, results, logs, cancellation and recovery. Retry an uncertain upload or submission with analysis submit trial-r1; the same directory retains one execution and its original request. To request cancellation, use analysis cancel trial-r1, then inspect status or wait for confirmation. Initialize a new directory for deliberately new work. Trials retain purpose: candidate_trial, their exact publication, grant and delegation even if activation or replacement occurs meanwhile. Removal of model administration, model access or compute authority blocks pending launch; observed execution retains normal drain behavior. Maintenance pauses new acceptance/claims. Retirement prevents fresh trials while accepted work and delivery finish.

model release status release-r1 and model release review release-r1 show publication-keyed trial evidence automatically, including failed and cancelled trials; no receipt or run ID needs copying from the analysis. When trials are available, release output also shows an exact-candidate initialization command with marked input-file and new-directory placeholders. analysis status trial-r1 links back to exact publication inspection and release review guidance. Collected scientific JSON and provenance are in trial-r1/results/; inspect those results before promotion. Installation readiness, execution success and scientific correctness are separate: a successful trial is execution evidence; authors own scientific validation. Trial success is advisory and never automatically activates or gates activation. Trials do not change the current publication, public admission or access policy. Validated, authorized retained publications can also be trialled after activation.

After reviewing the trial and completing your scientific checks, save the publication comparison and activate explicitly:

enumeray model release review release-r1
enumeray model release activate release-r1
enumeray model get example

Expect state: succeeded and scientific outputs {"doubled":4} for the scalar trial above. Substitute your model’s expected results and scientific assertions. A wait timeout only ends local observation; keep the original operation/run ID. The review displays current and proposed contracts, identities, installation, location, disclosure and trial evidence, and saves the expected-current guard. If another publication becomes current, activation stops. Run model release review release-r1 again to review the new comparison, then explicitly activate. status and resume preserve the guard. A lost activation reply is reconciled by status/resume without another activation request; an uncommitted activation still requires explicit activate. Follow updates.

Activation does not change visibility or execution access. Follow sharing to make the offering available to intended users. Keep the editable publication, saved operations and immutable release for updates or rollback.