Skip to main content
Governance11 min read

904 - Releases: what runs is what was released

A release applies the pending migrations and pins every automation and asset at a version. From then on the endpoints, forms, schedules and event runs execute the pinned versions, and a save changes nothing live until the next release. What a release records, what it refuses, who may make one, and why this boundary is what lets agent-written software run unattended.

What you will take away from this lesson

An agent can change a working system faster than any person can review the change. That is the whole promise, and without one more mechanism it would also be the whole problem. The mechanism is the release. Inside an application nothing an agent saves is live. What is live is a set of versions an administrator released, by name, on the record, and it stays exactly that set until the next release.

This lesson adds the shop’s parts to its record, reads what the first release would do, makes it, and then follows what happens when the agent saves a change afterward.

Learning Objectives

  1. 01Add an application’s parts and read what a release would change before it is made.
  2. 02State the two things a release does and the three things it records.
  3. 03Say what runs after a release, and what a save does to a released application.
  4. 04Name the four reasons a release is refused, and what a refused release changes.
  5. 05Explain why the release is the boundary that lets agent-written software run unattended.

Adding the parts

The automations and the storefront exist. Adding each to the application is what makes the release responsible for them.

Adding the parts

What the agent calls. This is the exchange the agent has with Plexara on your behalf, shown for the technical reader. You ask in plain language; you never type any of it.

→ manage_application
  { "command": "add_part", "application": "shop",
    "kind": "script", "part_id": "<shop-checkout's id>" }
→ manage_application
  { "command": "add_part", "application": "shop",
    "kind": "script", "part_id": "<shop-api's id>" }
→ manage_application
  { "command": "add_part", "application": "shop",
    "kind": "script", "part_id": "<shop-confirmation's id>" }
→ manage_application
  { "command": "add_part", "application": "shop",
    "kind": "script", "part_id": "<shop-maintenance's id>" }
→ manage_application
  { "command": "add_part", "application": "shop",
    "kind": "asset", "part_id": "<the storefront's id>" }
→ manage_application
  { "command": "add_part", "application": "shop",
    "kind": "source", "part_id": "shop-orders-outbox" }

← { "name": "shop", "current_release": 0,
    "parts": [ schema, 4 scripts, 1 asset, 1 source ] }

The owner’s agent adds the automations and the asset the owner owns. The webhook source is added by an administrator, because webhook sources are an administrator’s to manage. In the portal the same thing is one dialog: Add parts searches automations, assets and webhook sources by name and adds several at once, and a part another application already holds is listed with that application’s name.

Reading a release before it is made

An application always knows what its next release would do. The agent asks, and reports.

What the first release would do

What the agent calls. This is the exchange the agent has with Plexara on your behalf, shown for the technical reader. You ask in plain language; you never type any of it.

→ manage_application
  { "command": "get", "application": "shop" }

← {
    "application": { "name": "shop", "current_release": 0, ... },
    "current_release": null,
    "pending": [
      { "kind": "script", "part_id": "shop-checkout",     "from": 0, "to": 3 },
      { "kind": "script", "part_id": "shop-api",          "from": 0, "to": 2 },
      { "kind": "script", "part_id": "shop-confirmation", "from": 0, "to": 1 },
      { "kind": "script", "part_id": "shop-maintenance",  "from": 0, "to": 1 },
      { "kind": "asset",  "part_id": "storefront",        "from": 0, "to": 4 }
    ],
    "schema": {
      "connection": "acme-shop",
      "schema": "shop",
      "migration_version": 0,
      "released_version": 0,
      "pending": [1, 2, 3, 4, 5],
      "write_role": "shop_write"
    },
    "problems": [],
    "findings": []
  }

This is the statement the owner asked for in lesson 901: what the first release would contain, before anything is released. Five parts would be pinned at the versions shown, and five migrations would be applied. The trace names parts where the platform answers with their ids.

problems lists anything a release would refuse, and it is empty. The agent reports this in plain language, and the same facts are on the application’s page for the administrator who will make the release.

What a release does

A release is one act with two effects and a record.

What a release does

  1. 1

    It applies the pending migrations

    Each of the schema’s pending migrations is applied in order. Before any is applied for real, the ones that run in a transaction are run together in one transaction that is rolled back, so a migration that would fail refuses the release with nothing changed.

  2. 2

    It pins every part at a version

    Each automation is pinned at its newest saved version and each asset at its newest version. A site environment that is a part is pointed at the release the environment before it serves.

  3. 3

    It records what it did

    The release keeps the migration version it holds applied, each pin, and what changed: the parts whose pinned version moved and the migrations it applied, with the administrator’s name, the time and their note.

Schema and code move in the same act. There is no window in which new code runs against an old table, or a new table waits for code that has not arrived, because neither can be live without the other.

Release 1

The administrator read the application’s page, found nothing to refuse, and released.

The first release

What the agent calls. This is the exchange the agent has with Plexara on your behalf, shown for the technical reader. You ask in plain language; you never type any of it.

→ manage_application
  {
    "command": "release",
    "application": "shop",
    "note": "First release: catalog, checkout, API,
             confirmation, upkeep, storefront."
  }

← {
    "number": 1,
    "action": "release",
    "migration_version": 5,
    "changes": {
      "parts": [
        { "kind": "script", "part_id": "shop-checkout",     "from": 0, "to": 3 },
        { "kind": "script", "part_id": "shop-api",          "from": 0, "to": 2 },
        { "kind": "script", "part_id": "shop-confirmation", "from": 0, "to": 1 },
        { "kind": "script", "part_id": "shop-maintenance",  "from": 0, "to": 1 },
        { "kind": "asset",  "part_id": "storefront",        "from": 0, "to": 4 }
      ],
      "applied": [1, 2, 3, 4, 5],
      "reverted": []
    },
    "created_by": "[email protected]"
  }

An administrator makes the release, from the application’s page with the Release button or by asking their own agent. From this answer on, the shop is live: the tables exist, the checkout takes orders, and every part runs at the version named here.

What runs from now on

After the first release, every way of starting one of the shop’s automations runs the pinned version.

What runs after a release

Endpoints and forms

A request to the API and a submission to the checkout run the pinned version of their automation.

Schedules and events

The nightly run and each run started by an order event execute the pinned version.

Runs by hand

A run started from the automation’s page or through the agent executes the pinned version too. There is no path that runs anything else.

Assets

The portal serves the pinned version of an asset part, in the portal, through its shared links and wherever another asset refers to it. A pinned version is kept for as long as a release pins it.

Outside an application, a saved automation runs its newest version at the next request, as lesson 701 said. Inside one, the release decides. Removing a part from the application, or deleting the application, lets go of it, and it runs its newest version again; on a released application both are an administrator’s actions for that reason.

Saving a change to a released application

The owner asks for gift wrapping. The agent writes it, tests it and saves it. Here is what that does to the running shop.

A change after the first release

  1. 1

    The agent saves version 4 of the checkout

    The save runs the checkout’s tests on a copy of the database, as always, and is refused while one fails. Version 4 is saved.

  2. 2

    Nothing live changes

    Customers are still served by version 3, the pinned one. The application’s page shows the checkout as pinned at v3 with v4 as the latest.

  3. 3

    The record states the difference

    The pending list now holds one line: the checkout, from 3 to 4. If the change needed a new column, the migration that adds it is listed as pending beside it.

  4. 4

    An administrator releases, or does not

    Release 2 pins version 4 and applies the migration in one act. Until then the change exists, tested and waiting, and the shop is untouched.

A change that spans three automations and a migration reaches customers in one step, or not at all. The agent can work on the next version of the shop for a week, in the open, without one customer seeing a half-finished state.

An application named shop at release 3: its owner, schema, three migrations, page address and domain, then a Parts card listing two automations, a sales dashboard asset, a webhook source and the schema. One automation reads Pinned v4 with a marker that v5 is the latest, the others read pinned and latest, and the schema row shows migration 3 applied with one pending.
An application’s page on a demonstration deployment. Each part shows the version the release pinned. Where a newer version has been saved, the row says so: here one automation is pinned at v4 while v5 waits, and one migration is pending.

A refused release changes nothing

A release is checked before it acts. There are four reasons it stops, and each leaves the application exactly as it was.

When a release is refused

A part cannot be read

A deleted automation or asset, or a removed webhook source, refuses the release, naming the part.

A migration would fail

The pending migrations are first run together in a transaction that is rolled back. One that fails refuses the release before anything is applied. Should one still fail during the real apply, the migrations this release applied are reverted with their down migrations.

The application moved underneath

A release decided against a current release that another release has since replaced fails and records nothing. Two administrators cannot release over each other.

A shared library is at the wrong version

A part that loads one of the application’s own libraries at a version other than the one the release would pin refuses the release, naming the automation, the version it loads and the version to load.

A release that cannot be made changes nothing. There is no partial release to clean up after and no state called half-deployed. The refusal says what to fix, and the agent fixes it.

Why the release matters more than the code review

Key terms

Four terms describe a release and what leads up to it.

Key Terms

Release
One recorded act by an administrator that applies an application’s pending migrations and pins each automation and asset at its newest version.
Pin
The version of a part a release fixes. A pinned automation runs at that version however it is started; a pinned asset is served at that version.
Pending
What the next release would change: parts whose newest version is above their pin, and migrations not yet applied.
Problems
What the next release would refuse, reported before it is attempted and named part by part.

Related reading

governance
Governance

403 - Sharing prompts, and closing the loop with feedback

A procedure is only worth as much as the people who can run it. Plexara distributes a prompt two ways: a direct share to the teammates or teams you name, or a promotion to a whole role or company through the admin review queue. A shared prompt is live, not a copy. Feedback threads then carry corrections back, with a validation step and a path into the knowledge catalog, and the deprecate-and-supersede lifecycle retires old versions cleanly.

Governance

505 - Next month’s file

The new sheet arrives. Replacing the file’s content writes a new revision, and the registered table keeps reading the old one until it is registered again under the same name; the Scratch Tables page says so. This lesson covers the two cases that look alike and behave differently, moving the table forward, unregistering, what deleting the file does, saving the monthly procedure as a prompt, and the point at which a monthly file needs more than a join, which is where the 600 series begins.

Governance

605 - What a run may do, and the record it leaves

A run presents the roles its author held at the save, every call is authorized at that moment, and narrowing the persona takes effect on the next run. A save requires one format, work in main(), the structural rules, and tests that pass, reach the code, and read the data, and refuses a credential-shaped literal. A new version is replayed against recent successful runs, and one that changes what the automation does waits for the person’s agreement to a plain-language summary. The dialect has no network, no filesystem, no clock, and no imports beyond pinned libraries, so everything a script does is a platform call audited under the script’s own identity. The lifecycle, who sees what, state and checkpoints on a failed run, ownership and an administrator’s transfer, and the administrator’s view of every script and every run.