Test with journeys

View as Markdown

If you are verifying a Base Registry Engine (BReg) project, compile it offline, inspect what the compiler derived, and run its journeys against an isolated database before packaging it. Start from the facility template in Author a registry project:

bregctl init --template facility-registry facility

Check the project

bregctl check facility

Authoring check passed; registry revision sha256:<digest>.

An error refuses the project; a warning is a decision to review. Add --production for production package rules and --deny-warnings if your policy requires it. Check also reads dev-clients.yaml and the journey files under tests/, so a renamed Record type, profile, or Action fails there too.

Explain what the compiler derived

bregctl explain <subject> facility prints one compiled inventory without a database. The subjects are model (Record types and fields), access (what each profile may do), routes, queries (list queries per profile), actions, proposals (Proposal Actions only), events (declared deliveries), and lifecycle (the engine’s Proposal state transitions; it takes no project).

bregctl explain actions facility

  correct-address (proposal)
    inputs  facility, address-line, city, postal-code
    plan function  plans/correct-address.rhai
    write ceiling: patch facility, fields address-line, city, postal-code
    commit guard facility: revision unchanged

Add --format json for the complete definition and --production for production rules. For access, --scenario <file> evaluates synthetic claims against the profiles without verifying a token or reading a record. Explain shows the compiled contract, not runtime success.

Generate application artifacts

bregctl generate openapi facility --output facility-openapi

Every artifact family (bregctl generate --help) derives from the same model: fix the project, never a generated copy.

Declare a journey

tests/journeys.yaml lists journeys, each a sequence of steps. A step names a Record type or Action, a profile, synthetic claims, a request, and the expected outcome. The facility journey registers a facility, then reads it as a caller from another jurisdiction:

      - id: conceal-foreign-facility
        recordType: facility
        accessProfile: facility-reader
        claims:
          principal: synthetic-foreign-reader
          scopes: [registry:facility:read]
          purpose: facility-administration
          directClaims: {jurisdiction: zone-b}
        request: {type: get, recordCapture: facility}
        expect: {outcome: refusal, status: 404, problemCode: resource.not_found}

Keep the success and the refusal; add a step for each invariant your change affects.

A plan Function has an offline loop, with input keyed by authored input ID:

{"facility": "018f0c3e-7b1a-7c00-8000-000000000001", "address-line": "2 Corrected Road", "city": "Corrected city", "postal-code": "10300"}

bregctl project action-test facility --action correct-address --input correction-input.json

Ran the handler. Returned 1 effect.

--expect <file> asserts exact effects or a refusal. This proves the plan, not authority, guards, or a transaction.

Run with real credentials

This needs a separate schema-test database and runtime file with migration and runtime roles. Bind each protected step to a real short-lived credential whose claims match the step; synthetic claims authenticate nothing. Keep credentials outside the project.

bregctl test facility --runtime-config /path/to/runtime-test.yaml \
  --credentials /path/to/credentials.yaml --output /path/to/test-receipt.json

A passing run writes a receipt for that exact candidate; packaging accepts it and refuses changed inputs. A refused step names the failure; repair it and rerun into a fresh receipt path.

Journey file keys

Every key tests/journeys.yaml accepts, with its type and bounds. bregctl check adds the rules a schema cannot state.

Key path	Type	Required	Accepted values	Constraints
`apiVersion`The format and version this file is written in.	string	Yes	`id.registrystack.org/formats/breg/journeys/v1`	None specified
`journeys`	array	Yes	Not specified	`maxItems: 128` `minItems: 1`
`journeys[]`Array item	object	No	Not specified	None specified
`journeys[].id`A local identifier: a lowercase letter, then up to 63 lowercase letters, digits, `_`, or `-`.	string	Yes	Not specified	`pattern: ^[a-z][a-z0-9_-]{0,63}$`
`journeys[].steps`	array	Yes	Not specified	`maxItems: 128` `minItems: 1`
`journeys[].steps[]`Array item	object	No	Not specified	None specified
`journeys[].steps[].accessProfile`	string	Yes	Not specified	None specified
`journeys[].steps[].action`	string	No	Not specified	None specified
`journeys[].steps[].capture`Local capture alias for this step's result. Capture aliases must be unique throughout the journey, including aliases in captureResults; the reader checks this semantic rule.	string	No	Not specified	`pattern: ^[a-z][a-z0-9_-]{0,63}$`
`journeys[].steps[].captureResults`Maps disclosed Action result aliases to distinct local capture aliases. Capture aliases must be unique throughout the journey, including earlier captures; the reader checks this semantic rule.	object	No	Not specifiedSchema default, where declared: `{}`	None specified
`journeys[].steps[].captureResults.*`Map valueA local identifier: a lowercase letter, then up to 63 lowercase letters, digits, `_`, or `-`.	string	No	Not specified	`pattern: ^[a-z][a-z0-9_-]{0,63}$` `propertyNames.pattern: ^[a-z][a-z0-9_-]{0,63}$`
`journeys[].steps[].claims`	object	No	Not specified	None specified
`journeys[].steps[].claims.actorKind`	string	No	`agent` `human` `service`	None specified
`journeys[].steps[].claims.actorSubject`	string	No	Not specified	None specified
`journeys[].steps[].claims.directClaims`	object	No	Not specified	None specified
`journeys[].steps[].claims.directClaims.*`Map value	array \| string	No	Not specified	`propertyNames.maxLength: 512` `propertyNames.minLength: 1` `propertyNames.pattern: ^[^\u0000-\u001F\u007F-\u009F]+$`
`journeys[].steps[].claims.directClaims.*[]`Array item	string	Conditional	Not specified	None specified
`journeys[].steps[].claims.principal`	string	No	Not specified	None specified
`journeys[].steps[].claims.purpose`	string	No	Not specified	None specified
`journeys[].steps[].claims.requesterClient`	string	No	Not specified	None specified
`journeys[].steps[].claims.scopes`	array	No	Not specifiedSchema default, where declared: `[]`	`uniqueItems: true`
`journeys[].steps[].claims.scopes[]`Array item	string	No	Not specified	None specified
`journeys[].steps[].expect`	object	Yes	Not specified	None specified
`journeys[].steps[].expect.count`	integer	No	Not specified	`format: uint32` `maximum: 100` `minimum: 0`
`journeys[].steps[].expect.fieldId`	string	No	Not specified	None specified
`journeys[].steps[].expect.fields`A body of the registry's own HTTP API, carried as written: the registry reads its members, and null clears a field.	object	No	Not specifiedSchema default, where declared: `{}`	None specified
`journeys[].steps[].expect.members`Exact unordered collection membership, keyed by a prior Record capture. Omission keeps the historical shape-only collection check; an empty mapping explicitly expects no rows.	object	No	Not specified	`maxProperties: 100`
`journeys[].steps[].expect.members.*`Map value	object	No	Not specified	`propertyNames.pattern: ^[a-z][a-z0-9_-]{0,63}$`
`journeys[].steps[].expect.members.*.fields`A body of the registry's own HTTP API, carried as written: the registry reads its members, and null clears a field.	object	No	Not specifiedSchema default, where declared: `{}`	None specified
`journeys[].steps[].expect.outcome`	string	Yes	`refusal` `success`	None specified
`journeys[].steps[].expect.problemCode`	string	No	Not specified	None specified
`journeys[].steps[].expect.recordType`	string	No	Not specified	None specified
`journeys[].steps[].expect.refusalCode`	string	No	Not specified	None specified
`journeys[].steps[].expect.status`	integer	Yes	Not specified	`format: uint32` `maximum: 599` `minimum: 100`
`journeys[].steps[].id`A local identifier: a lowercase letter, then up to 63 lowercase letters, digits, `_`, or `-`.	string	Yes	Not specified	`pattern: ^[a-z][a-z0-9_-]{0,63}$`
`journeys[].steps[].recordType`	string	No	Not specifiedSchema default, where declared: `""`	None specified
`journeys[].steps[].request`One request form. `type` names the form; the members beside it are the form's own. Request bodies (`items`, `data`, `values`, `input`, and a change's `value`) are the registry's HTTP API bodies, carried as written.	object	Yes	Not specified	None specified
`journeys[].steps[].request.bbox`	object	Conditional	Not specified	None specified
`journeys[].steps[].request.bbox.east`	string	Conditional	Not specified	None specified
`journeys[].steps[].request.bbox.north`	string	Conditional	Not specified	None specified
`journeys[].steps[].request.bbox.south`	string	Conditional	Not specified	None specified
`journeys[].steps[].request.bbox.west`	string	Conditional	Not specified	None specified
`journeys[].steps[].request.changes`	array	Conditional	Not specified	None specified
`journeys[].steps[].request.changes[]`Array item	object	Conditional	Not specified	None specified
`journeys[].steps[].request.changes[].field`	string	Conditional	Not specified	None specified
`journeys[].steps[].request.changes[].value`A body of the registry's own HTTP API, carried as written: the registry reads its members, and null clears a field.	Not specified	Conditional	Not specified	None specified
`journeys[].steps[].request.count`	boolean	Conditional	Not specifiedSchema default, where declared: `false`	None specified
`journeys[].steps[].request.data`A body of the registry's own HTTP API, carried as written: the registry reads its members, and null clears a field.	object	Conditional	Not specified	None specified
`journeys[].steps[].request.etagCapture`A local identifier: a lowercase letter, then up to 63 lowercase letters, digits, `_`, or `-`.	string	Conditional	Not specified	`pattern: ^[a-z][a-z0-9_-]{0,63}$` or No bound
`journeys[].steps[].request.idempotencyKey`	string	Conditional	Not specified	None specified
`journeys[].steps[].request.input`A body of the registry's own HTTP API, carried as written: the registry reads its members, and null clears a field.	object	Conditional	Not specifiedSchema default, where declared: `{}`	None specified
`journeys[].steps[].request.items`	array	Conditional	Not specified	None specified
`journeys[].steps[].request.items[]`Array itemA body of the registry's own HTTP API, carried as written: the registry reads its members, and null clears a field.	object	Conditional	Not specified	None specified
`journeys[].steps[].request.items[].data`A body of the registry's own HTTP API, carried as written: the registry reads its members, and null clears a field.	object	Conditional	Not specified	None specified
`journeys[].steps[].request.items[].type`	string	Conditional	`create`	None specified
`journeys[].steps[].request.path`	string	Conditional	Not specified	None specified
`journeys[].steps[].request.preconditions`	object	Conditional	Not specified	None specified
`journeys[].steps[].request.preconditions.*`Map value	object	Conditional	Not specified	`propertyNames.maxLength: 512` `propertyNames.minLength: 1` `propertyNames.pattern: ^[^\u0000-\u001F\u007F-\u009F]+$`
`journeys[].steps[].request.preconditions.*.conditionCapture`	string	Conditional	Not specified	None specified
`journeys[].steps[].request.preconditions.*.ifMatch`	string	Conditional	Not specified	None specified
`journeys[].steps[].request.proposalCapture`A local identifier: a lowercase letter, then up to 63 lowercase letters, digits, `_`, or `-`.	string	Conditional	Not specified	`pattern: ^[a-z][a-z0-9_-]{0,63}$`
`journeys[].steps[].request.recordCapture`	string	Conditional	Not specified	None specified
`journeys[].steps[].request.select`	array	Conditional	Not specifiedSchema default, where declared: `[]`	`uniqueItems: true`
`journeys[].steps[].request.select[]`Array item	string	Conditional	Not specified	None specified
`journeys[].steps[].request.selector`	string	Conditional	Not specified	None specified
`journeys[].steps[].request.submissionCapture`A local identifier: a lowercase letter, then up to 63 lowercase letters, digits, `_`, or `-`.	string	Conditional	Not specified	`pattern: ^[a-z][a-z0-9_-]{0,63}$`
`journeys[].steps[].request.top`	integer	Conditional	Not specified	`format: uint32` `maximum: 100` `minimum: 1`
`journeys[].steps[].request.transition`	string	Conditional	`apply` `cancel` `edit` `get` `get-review-context` `get-review-status` `rebase` `retry` `revise` `start` `submit`	None specified
`journeys[].steps[].request.type`	string	Yes	`batch` `create` `get` `import` `invoke` `list` `lookup` `patch` `proposal` `query` `read-path` `target-conditions`	None specified
`journeys[].steps[].request.values`A body of the registry's own HTTP API, carried as written: the registry reads its members, and null clears a field.	object	Conditional	Not specifiedSchema default, where declared: `{}`	None specified
`kind`The kind of document this file is.	string	Yes	`BRegJourneys`	None specified