Releasing a prompt change

The steps

ael prompt-diff --old ./released --new ./working --entry advisor.node.ael
ael prompt-package --root ./working --entry advisor.node.ael --model advisor-model --provider main --context-policy default --configuration-sha256 SHA256 --source-revision r42 > candidate.json
ael eval --root ./working --suite suite.json --native-root DIRECTORY --worker WORKER --worker-sha256 SHA256 --output report.json
ael prompt-plan --baseline baseline.json --candidate candidate.json --report report.json --rollout percent:10 --output plan.json
ael prompt-publish --store ./releases --tenant acme --agent advisor --package candidate.json --root ./working
ael 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

ael prompt-diff compares two versions of a project and ael eval produces the evaluation report the plan needs. Promotion to stable and rollback are the same store commands, ael prompt-promote and ael prompt-rollback; ael prompt-status shows what is active.

ael prompt-package

ael prompt-package --root PROJECT --entry NAME.node.ael --model LABEL --provider LABEL --context-policy LABEL --configuration-sha256 SHA256 --source-revision LABEL

It prints the node's behaviour 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.

Locked dependencies

When the project's pack.ael declares packages, the behaviour 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.

ael prompt-package reads only the project's two files and consults no registry. It refuses to make a package when:

• pack.ael declares dependencies and the project has no pack.lock (PROMPT_LOCK_MISSING);
• pack.lock cannot 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.ael content 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 .package folder 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 the dependency_graph summary, 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 ael pack install and review the new lock, then package the node again.

ael prompt-plan

ael 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.

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 behaviour that no longer matches its dependencies.

ael prompt-publish

ael 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.

ael prompt-activate

ael 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 ael 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.