Releasing a prompt change
In the Open Engineering Language, a prompt change is a release of business logic. Four commands take it from your working project to an approved rollout: oel prompt-package records what a node's behavior is, oel prompt-plan shows what a release would change, oel prompt-publish stores the package and oel prompt-activate begins the rollout you approved. None of them starts a model or reads a credential, and none changes what is running until you approve a plan by its digest.
The steps
oel prompt-diff --old ./released --new ./working --entry advisor.node.oel
oel prompt-package --root ./working --entry advisor.node.oel --model advisor-model --provider main --context-policy default --configuration-sha256 SHA256 --source-revision r42 > candidate.json
oel eval --root ./working --suite suite.json --native-root DIRECTORY --worker WORKER --worker-sha256 SHA256 --output report.json
oel prompt-plan --baseline baseline.json --candidate candidate.json --report report.json --rollout percent:10 --output plan.json
oel prompt-publish --store ./releases --tenant acme --agent advisor --package candidate.json --root ./working
oel prompt-activate --store ./releases --tenant acme --agent advisor --baseline baseline.json --candidate candidate.json --report report.json --rollout percent:10 --root ./working --approver NAME --approve PLAN_SHA256
oel prompt-diff compares two versions of a project and oel eval produces the evaluation report the plan needs. Promotion to stable and rollback are the same store commands, oel prompt-promote and oel prompt-rollback; oel prompt-status shows what is active.
oel prompt-package
oel prompt-package --root PROJECT --entry NAME.node.oel --model LABEL --provider LABEL --context-policy LABEL --configuration-sha256 SHA256 --source-revision LABEL
It prints the node's behavior package as JSON, with the package's digest. The package is immutable and identified by its content: the digest of the resolved prompt, the digest of the node's input and output contract, the model, provider, context policy and configuration you name, and the source revision.
| Option | Meaning |
|---|---|
--root PROJECT | The project folder. |
--entry NAME.node.oel | The node to package. |
--model, --provider | The labels of the model binding the release uses. |
--context-policy | The label of the rules that build the node's context. |
--configuration-sha256 | The digest of the configuration the release runs with. |
--source-revision | A label for the source revision the package was made from. |
Locked dependencies
When the project's pack.oel declares packages, the behavior was built against the packages its pack.lock pins, so the package records them. It carries the identity of the accepted lock and, for every locked package, its id, name, version and archive digest. A package of a project without dependencies has neither, and its digest is the one it always had.
oel prompt-package reads only the project's two files and consults no registry. It refuses to make a package when:
pack.oeldeclares dependencies and the project has nopack.lock(PROMPT_LOCK_MISSING);pack.lockcannot be read (PROMPT_LOCK_UNREADABLE) or was resolved for another folder than the project root (PROMPT_LOCK_SCOPE);- the lock was resolved from other
pack.oelcontent than the current one, so it is stale (PROMPT_LOCK_STALE); - the lock is not a closed graph, because a package or the project itself depends on a package the lock does not pin (
PROMPT_LOCK_GRAPH); - a locked package that is installed in the project's
.packagefolder holds other content than the lock pins, or is only partly installed (PROMPT_LOCK_GRAPH, naming the pin). A locked package that is not installed at all is reported in thedependency_graphsummary, not refused: the lock is the pin and the folder is a convenience.
Each refusal is a structured diagnostic in JSON with a code, a message and a detail. Run oel pack install and review the new lock, then package the node again.
oel prompt-plan
oel prompt-plan --baseline PACKAGE.json --candidate PACKAGE.json --report EVAL_REPORT.json --rollout full|percent:N|tenants:A,B
A plan is the reviewable statement of a release. It names the digests of the baseline and the candidate, the kinds of change between them, the rollout and the evaluation report that backs it. The plan is refused when the evaluation evidence is not promotable, belongs to another node, or when the candidate equals the baseline. A change of the node's contract is refused unless you pass --allow-contract-change.
| Option | Meaning |
|---|---|
--baseline, --candidate | The two packages, as oel prompt-package printed them. |
--report | The offline evaluation report of the candidate. A live evaluation is never promotable. |
--rollout | full, percent:N for a share of subjects, or tenants:A,B for named tenants. |
--allow-contract-change | Allow a candidate whose input or output contract differs from the baseline's. |
--output PLAN.json | Also write the plan to a file. |
--root PROJECT | Also check the candidate against the project's current lock. |
The kinds of change are prompt, source, contract, model, provider, configuration, context_policy and dependencies. dependencies means the accepted lock differs between the two packages.
The plan prints a dependencies block that shows what the candidate puts into service: its lock identity, the lock identity of the baseline, every pin of the candidate and the pins that moved. A moved pin shows the version and archive digest on each side, or that the package is new or dropped. The plan's digest covers the candidate package and with it its lock and pins, so approving the plan approves them.
With --root PROJECT, the plan is also refused (PROMPT_LOCK_CHANGED) when the candidate was packaged under a lock that is no longer the project's accepted one. The diagnostic names each pin that moved since, so you package the node again and run the evaluation again instead of releasing a behavior that no longer matches its dependencies.
oel prompt-publish
oel prompt-publish --store DIRECTORY --tenant T --agent A --package PACKAGE.json [--root PROJECT]
It stores the package in the release store by its content and changes nothing that is active. The report names the package digest, the lock identity the package carries and the number of pins. With --root PROJECT the same lock check as in the plan applies.
oel prompt-activate
oel prompt-activate --store DIRECTORY --tenant T --agent A --baseline PACKAGE.json --candidate PACKAGE.json --report EVAL_REPORT.json --rollout full|percent:N|tenants:A,B --approver NAME --approve PLAN_SHA256
It begins the rollout of an approved plan. The command builds the plan again from the same files, and the approval must name that plan's digest, the plan_digest that oel prompt-plan printed. An approval can therefore only name a plan a reviewer could have been shown. Writes to the store are compare-and-swap: a stale or concurrent write is refused as a conflict and is never merged. With --root PROJECT the lock check applies here too.
Runs already under way stay pinned to the version they were admitted with. Evaluations and prompt releases describes promotion and rollback.
Output
Every command prints a JSON report. The lock refusals above print their diagnostic as JSON, with a code, a message and a detail that names the pins involved, so a script can read the reason without parsing text.
Related
- Comparing prompts: how a prompt change shows before it is packaged.
- Running evaluations: the evidence a plan needs.
- Writing the lock file and Installing declared packages: where the pins come from.
- Evaluations and prompt releases: versions, suites, promotion and rollback.