Change an active package

If you operate Registry Casework, a policy change reaches reviewers as a successor policy package applied to the database the runtime serves. Here you make one against the development session you left running in Staff the directory, on the project as Author a Casework policy left it. In production the order differs in one respect: stop every process serving the old package before you apply, as Deploy Registry Casework explains.

Change the project

Open a terminal in the directory that holds tutorial-work and go to the project. Make sure the session is running before you edit anything; dev start reuses a running session and restarts a stopped one on its ports:

caseworkctl dev start

{"directory": {"revision": 1, "teams": 1}, "state": "ready"}

Rename the queue reviewers see. In casework.yaml, change the decisions label you set when you authored the policy:

decisions:
  label: Licence decisions
  label: Licence applications

Package the successor

Write the changed project as a package of its own. The running session keeps serving its own package, which stays untouched:

caseworkctl package . --output package-2

{
  "output": "package-2",
  "packageDigest": "sha256:<digest>",
  "secretsIncluded": false
}

The package digest identifies these exact bytes; a change record keeps it.

Point a runtime file at it

The session’s runtime file is .casework/dev/operator.yaml, and its package.root names the session’s package. Copy it and point the copy at package-2. The caseworkctl operator commands take the file as an absolute path:

sed "s#^  root: .*#  root: $PWD/package-2#" .casework/dev/operator.yaml > successor.yaml
next="$PWD/successor.yaml"

Only the two-space root: line under package changes; secretProviders.file.root is indented further and stays as it was.

Plan the change

plan compares the candidate with the database’s activation ledger and its open reviews, and writes nothing:

caseworkctl plan --runtime-config "$next"

{"changesPending": true, "planKind": "successor", "refusals": []}

A successor with no refusals strands no open review. A candidate that removed the decisions queue while a request still waited in it would be refused here with casework.activation.stranded-work.

Apply it

Apply under a reference your change record keeps:

caseworkctl apply --runtime-config "$next" --operator-reference tutorial-change-1

{"applyOrder": 2, "planKind": "successor", "predecessorPackageDigest": "sha256:<digest>"}

The ledger now names package-2 as active, with the session’s package as its predecessor. Applying it again is refused, because there is nothing left to apply:

caseworkctl apply --runtime-config "$next"

error[casework.activation.already-active] runtime.yaml:/package
  package sha256:<digest> is already the active package in this database; nothing needs applying
  next: The package is already active. Check caseworkctl status before choosing a different package.
1 error, 0 warnings

Read the activation history

caseworkctl status --runtime-config "$next"

{"singleRoleStatement": "single-role mode: the ledger check catches a wrong package, but not someone holding this credential"}

history lists both activations. Single-role mode means the session’s runtime credential can write the ledger; a deployment gives the runtime a role of its own.

The session’s runtime is still serving the package it started with: a running process never rereads the ledger, and it would go on admitting work under the old package. That is why a deployment stops the predecessor before apply and starts the successor straight after.

Stop the session

The session cannot pick up the successor, so stop it:

caseworkctl dev stop

Because casework.yaml changed while the session holds records, it refuses to start again. When you are done with it, caseworkctl dev stop --remove deletes its database, credentials, and audit journal; keep anything you need first.