initiative-plugin-sdk 7.1.0 → 8.0.0

package/README.md

@@ -16,7 +16,7 @@ holds its tokens, and builds its manifest.
 | `initiative-plugin-sdk/widget` | What a widget is handed, and the scenes it returns |
 | `initiative-plugin-sdk/parts` | The components a part's tree is built from: `Section`, `Stack`, `Field`, `Value`, `Text`, `Button` |
 | `initiative-plugin-sdk/jsx-runtime` | JSX for a part's tree, with no React |
-| `initiative-plugin-sdk/testing` | A declarative plug-in's requests and maps, run against recorded vendor answers |
+| `initiative-plugin-sdk/testing` | A declarative plug-in's requests, maps and writes, run against recorded vendor answers |
 | `initiative-plugin-sdk/plugin-api.json` | The plug-in API contract: the OpenAPI document of every route a plug-in may call |
 | bin `initiative-plugin` | `init`, `build`, `pack`, `dev`, `validate`, `keygen`, `uid`, `schema` |
 
@@ -82,8 +82,9 @@ export default definePlugin({
   [`manifest.contract.json`](manifest.contract.json): `vendor`, `connections`
   (keyed by id), `webhooks`, `pages` (keyed by id),
   `dashboards`, `fields` (keyed by metadata key), `parts` and `actions` (keyed
-  by id). The types are generated from the contract, so every term the
-  contract declares has a type here.
+  by id), `settings` (keyed by setting key) and `help`. The types are
+  generated from the contract, so every term the contract declares has a type
+  here.
 - **Features follow from what is filled in.** A plug-in with widgets declares
   `widgets`, and so on.
 
@@ -170,12 +171,81 @@ hooks: {
 - `community_status` runs whenever the community's standing changes. The same
   value rides every call as `community_status`, so a missed hook is caught up
   on the next call.
-- `entitlement` carries the deployment's statement of what this community
-  holds of the plug-in: `values`, whose keys are agreed between the plug-in
-  and the deployment's issuer, and a `version` that rises with each
-  statement. Statements can repeat or arrive out of order, so keep the
-  highest version you have seen and ignore a lower one. A deployment with no
-  issuer never sends one.
+- `entitlement` carries billing's statement of what this community holds of
+  the plug-in: `values`, whose keys are agreed between the plug-in and
+  billing, and a `version` that rises with each statement. Statements can
+  repeat or arrive out of order, so keep the highest version you have seen and
+  ignore a lower one. A deployment with no billing never sends one. The SDK
+  verifies each statement before your hook sees it: see
+  [Entitlement statements](#entitlement-statements).
+
+### Entitlement statements
+
+What a community holds of a plug-in (its allowance, the packs it bought) is
+decided by billing, not by Initiative. So that a compromised Initiative cannot
+grant itself an entitlement, billing signs each statement with a key of its
+own, Initiative stores the statement and hands it on verbatim, and your
+plug-in checks billing's signature. Initiative can withhold a statement; it
+cannot mint or change one.
+
+A statement is a compact JWS. Its header is
+`{"alg": "EdDSA", "typ": "initiative-entitlement+jwt", "kid": …}`, and its
+claims are `{"iss": "initiative-billing", "listing_uid", "community_ref",
+"version", "values", "iat"}`. It has no expiry: it holds until a higher
+version replaces it. The `entitlement` hook's body, and what
+`client.entitlement()` reads, are both `{"statement": "<jws>"}`.
+
+Billing's public key reaches your plug-in from the deployment, never from
+Initiative: it is the runtime fact `entitlement_issuer_key`, an SPKI PEM in
+`INITIATIVE_ENTITLEMENT_ISSUER_KEY_PEM`. `initiative-plugin build` adds that
+fact to the runtime of every plug-in with an `entitlement` hook, so you need
+not declare it, and refuses it under any other variable name.
+
+The SDK checks every statement, on the hook and on `client.entitlement()`, in
+this order, and refuses it at the first failure:
+
+1. the key is configured and is Ed25519; without one, every statement is
+   refused, and the plug-in logs why once;
+2. the header's `alg` is exactly `EdDSA` and its `typ` exactly
+   `initiative-entitlement+jwt`: the header never chooses the algorithm, so
+   `alg: none` or an HMAC trick goes nowhere;
+3. the Ed25519 signature over the JWS signing input;
+4. `iss` is `initiative-billing`, `listing_uid` is your plug-in's own `uid`,
+   `version` is a whole number of one or more, and `values` is an object.
+
+Only then is your hook called, with `version` and `values` taken from the
+verified claims and nothing else in the body. A refused statement is answered
+`422 {"error": "statement-refused", "detail": "<reason>"}` and never reaches
+your hook; `client.entitlement()` throws `EntitlementStatementError`, whose
+`reason` is one of `no-key`, `bad-key`, `malformed`, `alg`, `typ`,
+`signature`, `iss`, `listing` or `claims`.
+
+**What it does not cover.** `community_ref` is billing's own pairwise
+reference for the community, which your plug-in cannot relate to the
+`installation` Initiative names. Initiative still vouches for which community a
+statement is for, so a compromised Initiative could at worst copy a real,
+signed statement from one community onto another. That gap is accepted.
+
+**Alerts.** The SDK counts, for the process's life:
+
+- every statement by outcome, `applied` (verified and handed on) or
+  `refused-<reason>`;
+- every grant of an unlimited allowance (`monthly_allowance: null`) to a
+  community whose last statement the process saw did not grant one. The memory
+  is the process's own, so after a restart the first such statement counts
+  again.
+
+`entitlementMetrics()` answers them as an object, and `entitlementMetricsText()`
+in the Prometheus text format, to append to what your metrics endpoint serves:
+`initiative_plugin_entitlement_statements_total{outcome="…"}` and
+`initiative_plugin_entitlement_unlimited_grants_total`. Alert on any
+`refused-*` and on any rise in unlimited grants. Neither ever refuses a
+correctly signed statement.
+
+**If you self-host.** A deployment that runs billing mints its statement
+keypair and fills `INITIATIVE_ENTITLEMENT_ISSUER_KEY_PEM` for each plug-in that
+declares the fact. A deployment with no billing leaves it unset: it sends no
+statements, and any that did arrive would be refused.
 
 ### The vendor's own setup
 
@@ -214,6 +284,43 @@ vendor: {
   key must be a vendor field, each answer is written at most once, and
   `client_secret`, `pem` and `webhook_secret` go to `secret` fields.
 
+### A token minted on demand
+
+A static connection's `token` has Initiative mint its access token rather than
+store one: it signs a JWT with a vendor key, posts it to the vendor's
+`exchange_url`, and caches the answer until shortly before it expires.
+`exchange_body` is a JSON body posted with it, such as the narrower
+permissions a token is asked for:
+
+```ts
+token: {
+  type: "jwt_bearer",
+  exchange_url: "https://api.tracker.example/installations/{installation_id}/tokens",
+  exchange_body: { permissions: { issues: "write", contents: "read" } },
+  iss: "{vendor.app_id}",
+  key: "{vendor.private_key}",
+},
+```
+
+`exchange_url`, `iss` and every string in `exchange_body` may name a vendor
+value as `{vendor.<key>}` and one of the connection's own fields as `{<key>}`;
+`validateManifest` refuses a name that neither declares.
+
+`exchange_body` may instead be an expression answering the body from
+`connection` alone, the connection's own non-secret fields, managed ones
+included, so the body can differ by connection: a vendor may refuse a token
+request naming a permission the installation does not hold. A body that names a
+vendor value stays an object. An answer that is not an object fails the token
+request, so the connection cannot be used until the expression answers one.
+`runExchangeBody` from `initiative-plugin-sdk/testing` answers the body
+Initiative posts for a connection's `fields` and `vendor` values.
+
+```ts
+// account_type is a managed field; only an organization's installation holds "members"
+exchange_body:
+  '{"permissions": $merge([{"issues": "write"}, connection.account_type = "organization" ? {"members": "read"} : {}])}',
+```
+
 ### Pages
 
 A page is one of your plug-in's screens, framed by Initiative:
@@ -267,14 +374,15 @@ What a plug-in adds to the views and pages of Initiative's items: tasks,
 calendar events, queue items, counters, gallery images and posts
 (`ITEM_KINDS`). Initiative draws all of it with its own components, so no
 plug-in code runs in a reader's browser, and the community's managers place
-it; a plug-in never places itself. They are a container plug-in's: a declarative
-plug-in holds no installation token to keep metadata with, and no handler to
-run an action.
+it; a plug-in never places itself. Any plug-in may declare them, container or
+declarative.
 
 **Metadata** is what the plug-in keeps on an item or on its own install: values
 by key (a lowercase letter, then lowercase letters, digits, `_` and `.`), held
-by Initiative and written with the installation token (`client.metadata`,
-below). Initiative enforces its sizes: a value of at most 8192 bytes as JSON,
+by Initiative. A container writes them with its installation token
+(`client.metadata`, below); for a declarative plug-in, Initiative writes them
+from the plug-in's expressions ([Declarative integrations](#declarative-integrations)).
+Initiative enforces its sizes: a value of at most 8192 bytes as JSON,
 32 keys and 64 KiB on one item, and 256 keys and 1 MiB on the install. A
 string of at most 255 characters can be found by.
 
@@ -304,16 +412,64 @@ fields: {
 editor's Add picker shows; `tone` is a badge's tone when its value names none
 (`accent`, `positive`, `negative`, `warning`, `neutral`, `muted`).
 
-**An action** runs one of the plug-in's write endpoints on one item, from a
-part's button, or from the item's own menu with `menu: true`. Initiative calls
-the endpoint as the installation, with `viewer` and `subject` set, and the
-handler does the work, usually writing metadata. Initiative then answers the
-reader with the item's metadata as it stands. With `confirm`, Initiative asks
-first.
+**A list field**, `list: true`, holds several values: its value is a list of
+elements, each one value of the field's `kind` with a `ref` of 1 to 255
+characters that tells it from the others. A `text`, `number`, `date`,
+`datetime` or `checkbox` element is `{ ref, value }`; a `link`, `badge` or
+`progress` element is the kind's own object with its `ref`, such as
+`{ ref, url, text? }`. Initiative keeps each element as a value of its own,
+held to the size of one value, and finds an element by its `ref`.
+
+**States** say what state a value is in, in the plug-in's own words: up to 4
+facets, each with up to 12 keys. A value names a key of each facet it is in as
+`state`, and Initiative draws one badge per facet, labelled in the reader's
+language. A list element, and a `link`, `badge` or `progress` value, carries
+`state` beside its other properties; a `text`, `number`, `date`, `datetime` or
+`checkbox` value that carries one is written as an element is, without the
+`ref`: `{ value, state }`.
+
+```ts
+fields: {
+  "tracker.issues": {
+    name: { en: "Issues" },
+    kind: "link",
+    list: true,
+    on: ["task"],
+    states: {
+      status: {
+        name: { en: "Status" },
+        values: { open: { label: { en: "Open" }, tone: "positive" }, closed: { label: { en: "Closed" }, tone: "muted" } },
+      },
+    },
+    actions: ["unlink"],
+  },
+},
+// an element: { ref: "12", url: "https://tracker.example/issues/12", text: "#12", state: { status: "open" } }
+```
+
+A list field's `actions` are offered on each of its elements, and each is
+offered on every item kind the field is. They are a declarative plug-in's: an
+action run from an element reads the element's `ref` as `element`, and a
+container's handler is told the item alone.
+
+**An action** runs on one item, from a part's button, from the item's own menu
+with `menu: true`, or from an element of a list field that offers it. A
+container plug-in's action names one of its write endpoints: Initiative calls
+it as the installation, with `viewer` and `subject` set, and the handler does
+the work, usually writing metadata. A declarative plug-in's names an endpoint,
+a `write`, or both, and Initiative does the work itself. Either way Initiative
+then answers the reader with the item's metadata as it stands. With `confirm`,
+Initiative asks first; with `admin_only: true`, only the community's admins may
+run it.
+
+`params` names the endpoint's params Initiative asks the reader for before it
+runs the action, in a form drawn from their own declarations: each one's type,
+label, and `options` or `options_from`. The endpoint is sent the reader's
+answers and nothing else, so every param it requires is among them.
 
 ```ts
 actions: {
-  "new-link": { name: { en: "New link" }, endpoint: "create-link", on: ["task"], menu: true },
+  "new-link": { name: { en: "New link" }, endpoint: "create-link", params: ["url"], on: ["task"], menu: true },
 },
 ```
 
@@ -331,8 +487,11 @@ plug-in's parts on one item.
 | `button` | `action`: an action's id; `variant?` (`primary`, `secondary`, `ghost`) | no |
 
 Every field and action a part names must be offered on each kind in the
-part's `on`. A tree is plain data, `{ type, props?, children? }`, or JSX through
-the SDK's runtime, which the build turns into the same data:
+part's `on`. A `text` node's text may name `{item.id}`, the item's id, and
+`{settings.<key>}`, one of the plug-in's [settings](#settings-and-help), which
+Initiative fills in when it draws the part; `validateManifest` refuses any
+other `{…}`. A tree is plain data, `{ type, props?, children? }`, or JSX
+through the SDK's runtime, which the build turns into the same data:
 
 ```tsx
 /** @jsxImportSource initiative-plugin-sdk */
@@ -362,6 +521,37 @@ children join the node that holds it, and `null` and `false` children are left
 out. `key` is JSX's own and is not passed on, which is why a field is named by
 `field`.
 
+### Settings and help
+
+**Settings** are values the community's admins see and may change on the
+install, keyed by setting key, at most 16. A part's text names one as
+`{settings.<key>}`, and a declarative plug-in's expressions read them as
+`settings.<key>`.
+
+```ts
+settings: {
+  prefix: { type: "string", label: { en: "Reference prefix" }, unique: true, assigned: "community_name" },
+},
+```
+
+A `unique` setting's value is held by no other community on the deployment for
+this plug-in, and is a lowercase letter, then lowercase letters and digits, 2
+to 16 characters in all (`^[a-z][a-z0-9]{1,15}$`), so a reference such as
+`acme-7` reads one way. With `assigned: "community_name"`, Initiative gives it a
+value when the community installs the plug-in: the letters and digits of the
+community's name, in lowercase, with a short random suffix when another
+community holds that value. An admin may rename it. The earlier values stay the
+community's, and expressions read them as `aliases.<key>`, so a reference made
+under one still resolves.
+
+**Help** is markdown, by language tag, at most 2000 characters in each.
+Initiative shows it behind a "?" on the headers of the plug-in's parts and on
+its settings:
+
+```ts
+help: { en: "Links issues to tasks. Name a task's reference, such as **acme-7**, in an issue's title to link it." },
+```
+
 ## 2. Widgets
 
 A widget is a module exporting `render`, typed from the endpoint it draws:
@@ -499,6 +689,11 @@ for (const { installation, active } of await initiative.installations()) {
 }
 ```
 
+An `Initiative` made by hand reads `client.entitlement()` only when it is given
+something to check statements with: `entitlements: new EntitlementStatements({
+listingUid: plugin.uid })`, which reads billing's key from
+`INITIATIVE_ENTITLEMENT_ISSUER_KEY_PEM`. The server's own client has one.
+
 - `asInstallation(installation, { initiative, scopes })` acts as the community,
   optionally narrowed to one initiative the plug-in is placed in and fewer scopes.
 - `asMember(installation, member, { purpose, initiative })` acts for one
@@ -527,7 +722,11 @@ for (const { installation, active } of await initiative.installations()) {
   path after `/c/{community}`) by hand, with the same scope check.
 - `client.callPlugin(publicId, endpointId, params)` calls another plug-in's public
   endpoint through Initiative. It needs `plugins:<publicId>` among the plug-in's
-  scopes, granted by the community.
+  scopes, granted by the community. A plug-in that uses whichever plug-ins a
+  community lets it sets `callsPlugins: true` (the manifest's
+  `service.calls_plugins`) instead of naming each: a community that installs
+  another plug-in is asked there whether this one may use it, which grants the
+  scope.
 - `client.metadata`, the plug-in's metadata, always on the installation's
   token: `get(itemKind, ids)` answers each item's values by id;
   `set(itemKind, id, values)` writes some of one item's values, a null
@@ -540,7 +739,8 @@ for (const { installation, active } of await initiative.installations()) {
   token, `client.reportConfigStatus({ state, detail })`, and
   `client.emitEvent({ eventType, payload, initiativeId })`.
 - What the community holds of the plug-in: `client.entitlement()` reads the
-  statement the `entitlement` hook delivers, or null when there is none, and
+  statement the `entitlement` hook delivers, verified the same way, or null
+  when there is none, and
   `client.reportUsage({ meter, period, quantity })` reports a meter's total
   for one `YYYY-MM` period. The total is the whole period's, never an
   increment, so repeating a report is harmless. Only meters the deployment
@@ -620,7 +820,11 @@ It holds nothing that raises a privilege. Resources, network rules, hostnames
 and every key and password stay the deployment's:
 
 - `facts` come from a fixed list: `app_url`, `app_origin`, `app_api_public`,
-  `app_api_internal`, `page_origin` and `port`.
+  `app_api_internal`, `page_origin`, `port` and `entitlement_issuer_key`
+  (billing's statement key, added for you with an `entitlement` hook; see
+  [Entitlement statements](#entitlement-statements)). There is no other
+  channel to Initiative's own services: billing reaches a plug-in only through
+  Initiative.
 - `settings` are names the operator fills.
 - `secrets` are generated by the deployment and kept.
 
@@ -668,7 +872,9 @@ A plug-in that only calls a vendor's API and reshapes the answer needs no
 container. Name the `hosts` it calls and give each endpoint a `request` and a
 `map` in place of a handler: Initiative makes the call with the connection's
 credential, and maps the answer itself. The plug-in has no `service` block, no
-image and nothing to run, and its listing registers it as `declarative`.
+image and nothing to run, and its listing registers it as `declarative`. It
+may still keep values on Initiative's items, which its webhook events,
+schedules and actions write and its fields and parts show.
 
 ```ts
 // src/plugin.ts
@@ -744,8 +950,10 @@ it("lists a repository's open issues", async () => {
   `connection` (the non-secret fields of the connection its request names),
   `connections` (on an endpoint, each connection its `requires` names that the
   call has, by id: `connections.workspace.owner`), `now`, and once a call has
-  been answered `response` (`status`, `headers`, `body`). `build` parses
-  every one and fails with its place in the manifest when one does not parse.
+  been answered `response` (`status`, `headers`, `body`). Every expression
+  also reads `settings`, the install's [settings](#settings-and-help) by key,
+  and `aliases`, each unique setting's earlier values. `build` parses every
+  one and fails with its place in the manifest when one does not parse.
 - **Each evaluation is bounded** by the contract's `CAPS.expressionTimeMs`,
   `CAPS.expressionDepth` and `CAPS.expressionOutputBytes`; past one, or on an
   error, the call answers `unavailable: mapping-failed`. `evaluate` from
@@ -754,10 +962,40 @@ it("lists a repository's open issues", async () => {
   request's `connection` names, as `auth` says: `Authorization: Bearer
   <token>` unless `auth: { header, prefix }` says otherwise. Every address
   must be https on one of `hosts`, exact or with one leading `*.` label. A
-  request or step on an `interactive` connection names it in the endpoint's
-  `requires` too, or `build` fails. A call made as a member carries a
-  `static` connection's credential only when `requires` names it, and is
-  refused otherwise.
+  request or step naming an `interactive` connection for every call names it
+  in the endpoint's `requires` too, and is on no endpoint whose `actors`
+  include `installation`, or `build` fails: a call made as the installation
+  has no member's credential. A call made as a member carries a `static`
+  connection's credential only when `requires` names it, and is refused
+  otherwise.
+- **A connection per actor.** A write's request or step may name one
+  connection for each of the endpoint's `actors` in place of one for every
+  call, so a call made as the member carries the member's own credential and
+  one made as the installation the community's:
+
+  ```ts
+  export const comment = defineEndpoint({
+    direction: "write",
+    actors: ["member", "installation"],
+    params: {
+      number: { type: "int", label: { en: "Issue" }, required: true },
+      text: { type: "string", label: { en: "Comment" }, required: true },
+    },
+    returns: { id: "int" },
+    request: {
+      method: "POST",
+      url: '"https://api.tracker.example/issues/" & params.number & "/comments"',
+      body: '{"body": params.text}',
+      connection: { member: "account", installation: "workspace" },
+    },
+    map: '{"id": response.body.id}',
+  });
+  ```
+
+  `member` names an `interactive` connection and `installation` a `static`
+  one, for exactly the actors the endpoint declares. The member's needs no
+  `requires`: a call made as the member requires it. An expression's
+  `connection` holds the fields of the one the call carries.
 - **`steps`** in place of `request` makes up to three calls in order; each
   reads the earlier ones as `steps.<name>`, and so does the map.
 - **`paging`** on a request reads more pages before the map runs:
@@ -773,21 +1011,109 @@ it("lists a repository's open issues", async () => {
   three `steps`, a map to `{values, account_label}`, and `refuse_when` with
   its `code`, which read each step as `steps.<name>`) and a
   `health` check run on an interval. **Webhooks** take `events`, each mapping
-  a delivery to one of the plug-in's emissions, and `status` rows that set a
-  connection's state; a delivery may be routed by a `header` instead of a
-  body `path`.
-- **One plug-in is one kind.** A declarative plug-in has no handlers, hooks,
-  schedules or pages, and asks for no scopes; a container plug-in uses none of
-  these terms. `validateManifest` and `build` refuse a mix.
-
-`runEndpoint`, `runAfterConnect`, `runHealth` and `runWebhook` render each
-request as Initiative sends it, less the credential, answer it from the
-recorded `responses` in order, and return the requests beside the result or
+  a delivery to one of the plug-in's emissions, changes to its values, or
+  both, and `status` rows that set a connection's state; a delivery may be
+  routed by a `header` instead of a body `path`.
+- **Scopes** are read scopes alone, at the manifest's top level, and
+  `validateManifest` refuses any other: a declarative plug-in keeps its own
+  values on items it can read, and does not call Initiative. Initiative keeps
+  its values only on items those scopes read, such as tasks with
+  `projects:read`.
+- **Values** are written from a `write` expression: Initiative makes the
+  changes it answers, as the install. A **change** sets values by key,
+  `{"set": {"<key>": <value>}}`, the shape of `client.metadata.set`: a null
+  removes its key, and every value is held to the metadata caps. A list
+  field's value is its whole list of elements; its elements change by their
+  `ref` with `{"upsert": {"<key>": [<element>]}}`, which adds each element or
+  merges it into the one with its `ref` (the properties it gives replace that
+  element's, the rest stay, and its `state` merges by facet, so a write that
+  knows one fact changes that fact alone), and `{"remove": {"<key>": ["<ref>"]}}`. A
+  change gives at least one of `set`, `upsert` and `remove`, and changes each
+  key with only one. A **targeted change** adds its `target`:
+  `{"kind": "task", "id": 7}` for one item, `{"install": true}` for the
+  install, or `{"holding": {"key": "<key>", "value": "<text>"}}` for every item
+  on which the install holds that value under that key (a number or a boolean
+  as JSON writes it, a list element by its `ref`). A target the install cannot
+  read is skipped, one `write` answers at most 100 targeted changes
+  (`CAPS.writeTargets`), and a `write` answering nothing changes nothing.
+  - An **event** row's `write`, beside its `emit` and `map` or in their place,
+    answers targeted changes from `headers`, `payload`, `connection`, `now`,
+    `settings` and `aliases`. The first row whose `when` holds applies, its
+    emission and its write both.
+  - An **action** names an `endpoint`, a `write`, or both. The endpoint may be
+    a read, fetching what the `write` keeps, or a write that changes something
+    at the vendor. Initiative makes the endpoint's call with the `params` the
+    reader answered, on the credential its `actors` say, its expressions also
+    reading `item` (`{kind, id, title}`) and `element` (the `ref` of the list
+    element it was run from, if any), then the one change `write` answers from
+    `item`, `held` (the install's values on the item), `result` (the
+    endpoint's mapped answer), `params`, `element`, `settings`, `aliases` and
+    `now`.
+  - A **schedule** makes a read as the installation on an interval: `endpoint`
+    names a read endpoint whose `actors` include `installation`, `params`
+    answers its params from `since` (when the schedule last succeeded, or
+    null), `now`, `connection`, `settings` and `aliases`, and `write` answers
+    targeted changes from `result`, `since`, `now`, `settings` and `aliases`.
+    Its id is none of the plug-in's connections': Initiative keys connection
+    health checks by connection id.
+
+  ```ts
+  schedules: {
+    sync: {
+      every: "1h",
+      endpoint: "updated-issues", // returns numbers: int list, states: string list
+      params: '{"since": since}',
+      write:
+        '[$map(result.numbers, function($n, $i) { {"target": {"holding": {"key": "issue.number", "value": $string($n)}}, "set": {"issue.state": result.states[$i]}} })]',
+    },
+  },
+  actions: {
+    create: {
+      name: { en: "Create an issue" },
+      endpoint: "create-issue", // returns number: int, url: string
+      on: ["task"],
+      write: '{"set": {"issue.number": result.number, "issue.link": {"url": result.url, "text": "#" & result.number}}}',
+    },
+    link: {
+      name: { en: "Link an issue" },
+      endpoint: "link-issue", // takes number: int; returns number: int, url: string, state: string
+      params: ["number"],
+      on: ["task"],
+      write: '{"upsert": {"issues.linked": [{"ref": $string(result.number), "url": result.url, "state": {"status": result.state}}]}}',
+    },
+    unlink: { name: { en: "Unlink" }, on: ["task"], write: '{"remove": {"issues.linked": [element]}}' }, // a list field's element action
+  },
+  ```
+
+  Wrap a list a `write` answers in `[ ]`: a JSONata path matching one item
+  answers it alone, and a run refuses a lone change where a list belongs.
+- **One plug-in is one kind.** A declarative plug-in is a manifest Initiative
+  runs, with no plug-in code: it has no handlers, hooks or pages. A container
+  plug-in ships code, which Initiative calls, and uses none of the declarative
+  terms. Any plug-in may keep values on items in Initiative: a container
+  writes them with its installation token, and for a declarative plug-in
+  Initiative writes them from the plug-in's expressions. `validateManifest`
+  and `build` refuse a mix.
+
+`runEndpoint`, `runAfterConnect`, `runHealth`, `runAction` and `runSchedule`
+render each request as Initiative sends it, less the credential, answer it from
+the recorded `responses` in order, and return the requests beside the result or
 the code the run answered. `runEndpoint` takes each connection's fields by id
-in `connections`; it has no actor, so it does not refuse a call the way
-Initiative would for who is making it. A run fails when a request has no recorded answer
-left, when an answer is left over, or when the map's answer does not fit the
-declared returns.
+in `connections`, and the `actor` the call is made as, by default the
+endpoint's first: a request naming a connection per actor carries that
+actor's. It does not refuse a call the way Initiative would for who is making
+it. `runAction` takes the `item`, what the install `held` on it, the `params`
+the reader answered, the `element` it was run from and its endpoint's `actor`,
+and answers the endpoint's `result` and the `change`; `runSchedule` takes
+`since`, makes its read as the installation, and answers the endpoint's
+`result` and the `writes`;
+`runWebhook` answers a delivery's `event`, `writes` and `status`. Every runner
+but `runExchangeBody` takes the install's `settings` and `aliases`. A run fails
+when a request has no recorded answer left, when an answer is left over, when
+the map's answer does not fit the declared returns, or when a `write` answers
+what is not a change: one that changes a key twice, gives a list field anything
+but a list of elements, or upserts or removes elements of a field that is not a
+list.
 
 ## A private plug-in
 
@@ -845,9 +1171,10 @@ npx initiative-plugin schema                   # the JSON Schema it checks again
 `validateManifest` runs the bundled JSON Schema, then the checks a schema
 cannot express: features against the blocks present, ids that must name
 something the manifest declares, connection, vendor setup and schedule rules,
-what a part's nodes and an action name, a part's size and depth,
-and every term the contract does not declare (a deployment discards those
-without saying so). The deployment also enforces byte-size caps.
+what a part's nodes, a list field's element actions and an action's `params`
+name, the placeholders in a part's text, a part's size and depth, and every
+term the contract does not declare (a deployment discards those without saying
+so). The deployment also enforces byte-size caps.
 
 ## The contract
 
@@ -929,7 +1256,14 @@ either the file's version or the client is stale.
 | `initiatives:read` | The initiatives the plug-in is placed in. |
 | `initiatives:moderate` | Acting as a moderator in an initiative it is placed in: everything there, within the plug-in's other scopes. Only on a token that asks for it (`level=moderator`) and is narrowed to that initiative. |
 | `community:admin` | Acting with a community admin's standing across the community, within the plug-in's other scopes. Only on a token that asks for it (`level=community_admin`) and is not narrowed to an initiative. |
-| `plugins:<public id>` | Calling that plug-in's public endpoints through Initiative. One per plug-in. |
+| `plugins:<public id>` | Calling that plug-in's public endpoints through Initiative, and reading the values it shows on items the plug-in can read. One per plug-in. |
+
+A container plug-in's `scopes` go in its manifest's `service` block. A
+declarative plug-in asks for read scopes alone, at the manifest's top level: it
+keeps its own values on items those scopes read, and does not call Initiative.
+A container plug-in with `callsPlugins: true` needs no `plugins:` scope in its
+manifest: a community that installs another plug-in is asked there whether
+this one may use it, and that grants `plugins:<public id>` for it.
 
 Writing implies reading. Within its scopes a plug-in still sees only what is open
 to the initiative, shared with the plug-in, or created by it — unless a token asks

package/dist/build.d.ts

@@ -52,7 +52,7 @@ export interface BuiltPlugin {
     listing?: ListingDeclaration;
 }
 /** What the listing writers read of a plug-in: its definition, or a {@link BuiltPlugin}'s. */
-export type ListedPlugin = Pick<AnyPlugin, "publicId" | "uid" | "name" | "scopes" | "hosts" | "hooks" | "listing">;
+export type ListedPlugin = Pick<AnyPlugin, "publicId" | "uid" | "name" | "scopes" | "callsPlugins" | "hosts" | "hooks" | "listing">;
 /** What a definition builds: the plug-in and its manifest, or every problem that stops it. */
 export type Compiled = {
     plugin: ListedPlugin;