Review a Proposal in Casework

Your registry can hold a Proposal until a person approves it. Here you connect one Action’s Proposals to a Casework ReviewPolicy, then point your Base Registry Engine (BReg) at Casework for the decision. The registry keeps submission and application; Casework records the decision and writes nothing to your registry.

Outcome: A checked Casework package paired with a registry Action, and Casework bound as that registry's review authority.
Time: About 20 minutes after both projects are ready
Level: Authoring and package verification
Prerequisites: Matching bregctl and caseworkctl binariesA tested BReg package whose Action requires reviewA Casework project with a matching ReviewPolicy and context providerA shell

Start from two projects built to pair

Create both projects from templates that already agree:

bregctl init --template facility-registry facility
caseworkctl init --template canonical-review review

In facility, the correct-address Action creates a Proposal that requires review by an authority named casework. In review, a context provider named facility-proposal-context lets reviewers see that Proposal: Casework reads it from your registry under each reviewer’s own access. For another Action, create its approval project with provider add after choosing its review grants.

Pairing reads the built registry package, not your editable source. Before you go on, test facility against its own database and seal its package with bregctl package, as Check, test, package walks through. Then name the paths and identifiers once:

casework_project=/absolute/path/to/review
breg_package=/absolute/path/to/facility-package
provider_id=facility-proposal-context
action_id=correct-address

Pair the Proposal context

The registry package exports the shape of the Proposal the Action creates, and the context provider pins the shape it expects. Preview whether they match; the preview writes nothing:

caseworkctl provider pair "$casework_project" \
  --provider-id "$provider_id" \
  --breg-package "$breg_package" --action-id "$action_id"

A working pair reports "ok": true, the verified contract, and the package’s registryRevision. Its readerAuthority names get-review-status with "sourceWrites": false: Casework only reads review status from your registry. Write the pair into the Casework project:

caseworkctl provider pair "$casework_project" \
  --provider-id "$provider_id" \
  --breg-package "$breg_package" --action-id "$action_id" --apply

The report now says "applied": true. If the pin and the export differ, the command exits 1 with casework.provider-pair.contract-mismatch; review the context changes and update the authored pins before pairing again. If the binaries differ, select the matching executable with --bregctl-bin.

Check and package the Casework project

Confirm offline that the two projects still agree, then build the package you deploy:

caseworkctl check "$casework_project" --against-breg-package "$breg_package"
caseworkctl package "$casework_project" --output ./paired-casework-package

The check compares the context contract and its exact schema bytes. It proves the projects agree, not that either service is reachable. Rebuild and recheck whenever the registry package changes.

Create a policy for another Action

For your own Proposal-mode Action, choose an approval pattern and a new Casework directory:

caseworkctl provider add ./action-review \
  --breg-project ./registry --action <action-id> \
  --pattern two-peer-approval --breg-package <sealed-package>

When BReg needs changes, the command exits 1 with casework.provider-add.breg-changes-needed, prints the missing YAML, and creates no project. Review the proposed grants and any bypass warnings, apply the intended changes to BReg, rebuild its package, and rerun. The proposed context shows used inputs and changed fields. Its changes projection requires a real records.get grant; the output also offers an inputs-only alternative. Documents are never proposed.

Once BReg is ready, the command creates the pattern with current-source pins and its exported schema, pairs, checks, and inspects the package. Add --package-output <new-directory> on creation to write that package. Without --breg-package, creation stops after checking and prints the pairing step. Repeating the command checks agreement without rewriting files. To package an existing project, use caseworkctl package --output. Replace the generated .test producer identities and configure runtime secret references before deployment.

Bind Casework as the review authority

A review authority is the service your registry asks for a decision. The registry project names it, and the registry’s runtime configuration binds it to Casework’s URL and a credential; Review authorities, declared twice shows both halves. On the Casework side, your registry is a trusted producer, the caller allowed to submit a ReviewRequest:

trustedProducers:
  facility-registry:
    profile: requester
    issuer: https://identity.example.test
    subject: facility-registry-review-producer
    trustedInitiatorIssuer: https://identity.example.test
    sourceNamespaces: [facility-registry]
    reviewPolicies: [facility-address-review]
    retention: {receiptRetentionDays: 30}

Three values in the registry’s binding must agree with that entry:

producerId equals the producer’s key, facility-registry. Both products fold it into each submission’s digest.
The binding’s profile, and its credential’s issuer and subject, equal the producer’s profile, issuer, and subject.
recoveryDays must not exceed receiptRetentionDays, which is at most 365. The registry retries an uncertain submission against an admission receipt Casework keeps only that long. No tool compares the two values.

sourceNamespaces lists the registry names this producer may submit for. Casework decides on the exact Proposal version and its effectDigest, and the registry accepts only a ReviewResult that matches them.

By default the registry polls Casework for results. To be called instead, add completionTokenRef and completionRecipient to the binding together, and give the producer a completion destination, the registry URL Casework calls, that presents the same token.

Read the signals

Submit a Proposal for the paired Action, then read it with an access profile that may apply it. While Casework reviews it, the Proposal’s apply link is unavailable with reason pending-review and recovery refresh. A reviewer then finds the work as a ReviewTask in Casework.

Hand-off faults read differently:

A credential that matches no producer, or a policy or source namespace the producer does not list, is refused with 403 operation.not-authorized. The registry logs a warning with the authority, status, and problem code, and the Proposal reads review-ended with recovery revise.
Every refusal of the hand-off for good, the one above included, reads review-ended. The Proposal, its list item and its submission read then carry handoffRefusal, such as {"code": "review.initiator-required"}. The code is review.initiator-required, review.initiator-excluded, review.policy-mismatch, or review.refused for any other refusal; the authority’s own text is never copied. The two initiator codes usually mean a service submitted work a person must submit, so let the person start or submit the Proposal.
A producerId that differs from the producer’s key fails the registry’s own acceptance check. The Proposal reads dependency-outage with recovery retry until recoveryDays pass, then review-ended. When a review never settles, check producerId first.

After the decision, the Proposal follows its usual states: applied, rejected, or submitted with Revise offered when changes are requested. Proposals covers those states; a Casework decision never grants authority to apply.

Registry Casework API