Sharing, administration, updates and rollback

Role: Model owner or co-admin for publication and access policy; the owner only manages co-admin membership, ownership transfer and archival. Prerequisites: An existing model and CLI login. Use the model ID example below; replace user/request/transfer IDs with values returned by your service.

Understand the independent controls

Control	Choices	What it changes
Current publication	A ready candidate selected with model publish	Scientific contract and installed execution path used for newly prepared runs
Visibility	listed, unlisted	Catalogue discovery; it does not grant execution
Run access	open, request, invite	Who can run the model
Administration	Owner and co-admins	Publication/access management and access to the model’s scientific run data

New models start with invite access and unlisted visibility. Activation does not share them. Unlisted models can still be discovered by authorized users who know their ID. Open access permits authenticated users to run subject to blocks and service/execution limits; it does not create anonymous access.

--generation is an optimistic concurrency guard. Read the model’s current generation, make one guarded change, then inspect again before another change. Do not guess the next generation or blindly repeat a conflicting management edit. Publication replacement instead uses a separate --expected-current guard.

Select request-based access

Inspect the model, copy its displayed numeric Generation, preview a deliberate policy, then apply it. Replace OBSERVED_GENERATION with the value from that immediately preceding read:

umask 077
enumeray access policy example
# Replace this placeholder with the Generation value just displayed:
GENERATION=OBSERVED_GENERATION
enumeray access set-policy example --mode request --visibility listed \
  --generation "$GENERATION" --dry-run
enumeray access set-policy example --mode request --visibility listed \
  --generation "$GENERATION"
enumeray access policy example

Expect mode: request and visibility: listed. Omitting --visibility preserves the current visibility. Pass it explicitly when you intend to change discovery.

The preview returns the model ID, observed mode/visibility/generation and proposed mode/visibility. Dry-run sends no policy update. Normal apply shows a concise before/after summary on stderr; --json emits only the existing apply response. Policy inspection and dry-run need models:read; applying also needs access:manage.

A mismatched generation or failed inspection stops the CLI before mutation. A concurrent edit between inspection and apply is rejected by the server. The CLI never refreshes the guard or retries automatically. An exact retry after a lost successful reply also conflicts with the original generation; inspect access policy and model audit before deciding on another change.

A prospective user runs in their own logged-in profile:

enumeray access request example --message 'Please allow runs for the materials study.'

As owner/co-admin, inspect requests and use the actual request’s id:

enumeray access requests example
enumeray access decide example REQUEST_ID approved

Approval grants run access. Use rejected to deny the request. Only the requesting user can choose withdrawn to withdraw their own request. Inspect the request inventory after an uncertain decision rather than creating duplicate requests.

Invite a particular recipient

Choose invite-only access with a newly observed generation:

enumeray model get example
# Replace this placeholder with the Generation value just displayed:
GENERATION=OBSERVED_GENERATION
enumeray access set-policy example --mode invite --visibility unlisted \
  --generation "$GENERATION"
enumeray access invite example --email colleague@example.org --output invitation.json
enumeray access invitations example

If you know the recipient’s service user UUID, use --user USER_UUID in place of --email. Exactly one recipient selector is required. --output must name a new file. The CLI saves a private JSON response containing id, model_id, token and expires_at; invitations expire after seven days.

Deliver this file or its token privately to the intended recipient. The invitation inventory does not reveal the token. An email-bound recipient must authenticate with the matching verified email; a user-bound invitation must be accepted by that user.

The recipient reads the token from the file into stdin, using their own CLI login:

python3 -c 'import json; print(json.load(open("invitation.json"))["token"])' \
  | enumeray access accept example
enumeray model get example

Do not pipe the entire JSON file into access accept: it expects the token alone. Keep tokens out of process arguments, shell history and shared repositories. The resulting run access is separate from co-admin membership.

Open access and explicit blocks

For a model intended for all authenticated users, use:

enumeray model get example
# Replace this placeholder with the Generation value just displayed:
GENERATION=OBSERVED_GENERATION
enumeray access set-policy example --mode open --visibility listed --generation "$GENERATION"

An explicit block overrides otherwise allowed run access:

enumeray model get example
# Replace this placeholder with the Generation value just displayed:
GENERATION=OBSERVED_GENERATION
enumeray access block example USER_UUID --generation "$GENERATION"

To remove the block, read a new generation and call:

enumeray model get example
# Replace this placeholder with the Generation value just displayed:
GENERATION=OBSERVED_GENERATION
enumeray access unblock example USER_UUID --generation "$GENERATION"

Unblocking removes the explicit block and creates an explicit run-access grant, including for request/invite modes. Use model audit example to inspect recorded management decisions.

Add or remove a co-admin

The owner can delegate model administration. Co-admins can manage publications/access and inspect every model run and its scientific data. Connector-only administrators see operational metadata unless separately authorized. Grant this role only when its scientific-data access is intended.

As the owner:

enumeray model members example
# Replace this placeholder with the Generation value just displayed:
GENERATION=OBSERVED_GENERATION
enumeray model member-add example --user USER_UUID --generation "$GENERATION"
enumeray model members example
enumeray model audit example

Remove membership with a newly observed generation:

enumeray model members example
# Replace this placeholder with the Generation value just displayed:
GENERATION=OBSERVED_GENERATION
enumeray model member-remove example --user USER_UUID --generation "$GENERATION"

Co-admins cannot add/remove other co-admins, transfer ownership or archive the model. The owner cannot use member commands on themselves. A run invitation does not grant any administrative authority.

Transfer ownership or archive

The current owner proposes a transfer:

enumeray model members example
# Replace this placeholder with the Generation value just displayed:
GENERATION=OBSERVED_GENERATION
enumeray model transfer example --to USER_UUID --generation "$GENERATION"

Deliver the returned transfer ID to that person. Logged in as the designated recipient, they explicitly accept:

enumeray model accept-transfer example TRANSFER_ID
enumeray model members example

A proposal alone does not change ownership. Intervening generation changes can invalidate acceptance; inspect ownership and arrange a fresh proposal when necessary.

To retire the entire model from new use, the owner runs:

enumeray model members example
# Replace this placeholder with the Generation value just displayed:
GENERATION=OBSERVED_GENERATION
enumeray model archive example --generation "$GENERATION"

Archival is a lifecycle action; it does not remove installed release files or retained run evidence. There is no model unarchive command. Inspect and preserve required runs/releases before retiring an offering.

Publish an update

Save the current editable declaration before editing, and preserve its release operation and installed files:

mkdir -p history/r1
cp publication.json history/r1/

Edit the science/mapping, update fixtures and scientific identities, and run your numerical/file tests. If installed code, dependencies or datasets change, copy the tested project into a new immutable release such as /opt/enumeray/models/example/r2 and set execution.release_path in publication.json to it. Do not modify r1. A schema/example-only change can reuse the old installation when the installed wrapper supports the new contract.

Freeze the tested complete declaration in a new release operation:

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

Repeat resume after interruption to reuse the exact saved candidate. It registers and waits for readiness without activating. Use the displayed Candidate ID with the existing candidate trial workflow. Inspect the trial’s results, logs and provenance and complete your scientific assertions. Trial success remains advisory.

Review the proposed publication and disclosure changes, then activate explicitly:

enumeray model release review release-r2
enumeray model release activate release-r2
enumeray model release status release-r2

Review saves the observed current publication as the activation guard. If the guard conflicts, inspect the competing publication and audit trail, then run review again before another explicit activate. Neither status nor resume changes that guard. An uncertain activation reply remains in the saved operation: status/resume can confirm that the candidate is current without inventing an activation receipt or issuing another activation request.

Newly prepared runs select the replacement; earlier accepted runs retain their original contract, publication, destination and installation. Keep their release files and original connectors available. Activation does not change visibility or access policy.

Move to a replacement context

For a host, account, backend or scratch-policy change, the connector owner creates a fresh context and grants you access. Verify the installed release under the replacement account, preserve the old declaration and operation, then edit publication.json with the new context and installation settings. The context supplies its driver; include execution.slurm_script for Slurm and omit it for process. Use a fresh saved release operation:

enumeray connector grant available
enumeray model release init example --file publication.json --directory release-new-context
enumeray model release resume release-new-context
# Trial the displayed candidate and complete scientific assertions.
enumeray model release review release-new-context
enumeray model release activate release-new-context

Even unchanged science and release files require a fresh publication, current grant and installation validation. Review location, disclosure and trial evidence before explicit activation. Connector ownership does not authorize author activation or move accepted runs. Coordinate the handoff: source cutover requires all live current publications moved or explicitly withdrawn by their model administrators. Withdrawing through model revoke-publication is permanent and retains its ordinary dispatch restrictions.

After cutover the source rejects fresh registration, activation, standard runs and candidate trials. Previously accepted queued runs either drain under ordinary eligibility checks or are cancelled while still queued, according to the owner’s explicit policy. Assigned work and delivery retain the original release and destination. Keep that release available until its obligations finish. The owner can then request retirement of obsolete configuration, including abandoned candidates, and wait for connector acknowledgement before final context retirement. Reopening a draining context does not undo cancellations, retirement requests, revocations or author activation decisions. Follow the complete author guidance and connector procedure when coordinating the replacement.

Roll back by creating a fresh publication

Select the prior publication from model publications example. Its retained scientific contract and physical installation settings are sufficient; the original local project is not required:

enumeray model release init example --rollback-from PRIOR_PUBLICATION_ID --directory rollback-r1
enumeray model release resume rollback-r1
enumeray model release status rollback-r1
# Review candidate trials and complete scientific checks before activation.
enumeray model release review rollback-r1
enumeray model release activate rollback-r1

Rollback allocates a fresh publication ID. Registration resolves your current active context grant and requests new connector validation. It does not copy the historical grant, internal installation key or readiness evidence, or reactivate the historical publication. Matching authorized installations can reuse their retained key through ordinary registration.

Source retirement releases the old configuration; its retained settings can still create a fresh candidate, but this does not prove that installed files remain. The release and context must still exist and be accessible. A revoked historical grant can be replaced for the fresh candidate. A permanently revoked installation remains unavailable across publications and grant reissue. Inspect the displayed source retirement/revocation limits and fresh readiness blockers.

Retire unused publication configuration

Keep candidates you still intend to validate, activate or use as rollback targets. After a replacement is current and earlier accepted work has finished, an owner or co-admin can retire unused configuration. Inspect the publication and read the model’s current generation immediately before the guarded change:

enumeray model publication example OLD_PUBLICATION_ID
enumeray model get example
# Replace this placeholder with the Generation value just displayed:
GENERATION=OBSERVED_GENERATION
enumeray model retire-publication example OLD_PUBLICATION_ID --generation "$GENERATION"
enumeray model publication example OLD_PUBLICATION_ID
enumeray model audit example

Retirement requests removal of that publication from required connector configuration. It preserves the immutable scientific definition, installation descriptor, validation, revocations, accepted runs and original retry receipts. An authorized current publication must be replaced or revoked first. Accepted queued, active or uncertain work and pending delivery keep a retirement request blocked until their references are released. Inspect configuration_retention for requested, blocked and retired state; its blockers counts identify queued runs, running runs, pending log archives and pending assignment uploads. A lost reply can be retried with the exact original generation. Another retained publication sharing the installation keeps its cache reference. The connector also retains configuration needed for local recovery or pending delivery, even after server retirement.

The request immediately prevents activating the old candidate and marks its rollback_availability as unavailable with configuration_retired. That is the old target’s retained configuration state, not an assertion about physical release files. A fresh publication can reacquire unchanged installation settings under current authorization and validate them again.

This action does not delete installed release files or published artifacts, and it does not clear a permanent installation revocation. A retired publication cannot be activated; rollback requires a fresh publication with current authorization and validation of an available release. Coordinate physical release retention with the connector owner. Retry a lost reply with the exact original generation; after a conflict, reread before making another change.

Permanently revoke a publication

When a particular publication must stop accepting, dispatching and launching new work:

enumeray model revoke-publication example PUBLICATION_ID
enumeray model publication example PUBLICATION_ID

This action is permanent for that publication; other publications sharing its retained installation are unaffected. Already executing work retains result delivery; users can still request cancellation or recover the original submission receipt. Publishing a replacement alone does not revoke accepted work. Rollback requires a fresh publication with current authorization/readiness.

A service operator can revoke the installation shared by several publications; that permanent installation revocation cannot be bypassed by cloning its descriptor. Coordinate such retirement with the connector/service owners and preserve evidence required by retained runs. Run inspection and cancellation/retries explain the user’s recovery path.

Team review and CI

The captured grant holder can create a named handoff with model release delegate DIRECTORY --user UUID --generation N. The reviewer adopts the existing candidate with model release init MODEL --candidate PUBLICATION --directory review-r1, initializes a separate trial with analysis init MODEL --candidate PUBLICATION --inputs INPUTS.json --directory review-trial-r1, reviews the displayed installation/disclosure, then explicitly submits with analysis submit review-trial-r1. Use analysis wait/status/logs/cancel/collect with that same trial directory. Release status/review includes the trial evidence automatically; the reviewer completes scientific checks before explicitly reviewing and activating the release. The original compute grant and installation remain pinned. See the author guide for retries, revocation, role changes and CI credentials.