Department services

What a service contract is

A department can publish a service: something it will do for the rest of the organization, declared rather than arranged in chat. A contract names

• the owner role, accountable for delivering it,
• the request fields somebody must fill in,
• the response fields the answer must carry,
• the obligation: what the department promises, and within how many hours,
• the escalation: who hears about it, and after how long,
• the evidence a response must cite before it counts as answered.

Before this, only three services existed end to end, each written by hand. Anything else went through agent chat, where nobody owns it, nothing is typed, and no evidence is required.

Publishing one

orgabot organization department service publish acme accounting close-review \
  --name "Close review" --owner controller \
  --input period:date:required --input "scope:choice:required:full|partial" \
  --output verdict:text:required \
  --promise "Reviewed within two working days." --within 48 \
  --escalate-to accounting-analyst --escalate-after 72 \
  --evidence document

A choice field lists its options after the required flag, separated by |.

The owner role is always a handler: accountability with no way to act on it is not accountability. A contract naming a role that does not exist, as an owner, a handler, or an escalation target, is refused at publish, because the request that discovers it is the one that sat unanswered.

Some things are refused outright, because they would publish cleanly and then fail the first real request:

• No inputs. A typed request with nothing declared is a chat message with extra steps.
• Escalating to the owner. Handing an unmet obligation back to the role that already owes it is not an escalation.
• An escalation window that is missing, zero, or not a number. A missing one used to publish cleanly and then mark every brand-new request escalated.
• An escalation that fires before the promise is due. Every request would escalate while still on time.
• A choice field with no options. Nothing could ever satisfy it.
• No required evidence. Without it, "done" is the only thing a handler has to say.

Requesting one

orgabot organization department service request acme accounting close-review \
  --as-role head-of-product --mission mission-42 \
  period=2026-07-31 scope=full

The request is validated against the contract, routed to the owner role, and stamped with the mission it came out of so the ask never becomes orphaned work. The requesting role must exist: a request attributed to a typo is work nobody owns.

A value is submitted as a number only when the contract declares that field as one. A reference like invoice=00123 keeps its leading zeros rather than becoming 123. Every refusal is reported at once, not one per round trip.

Submitting is idempotent by content: an identical open request from the same role returns the existing one rather than raising a second. A retried submit after a dropped connection is the common case, and two open requests for one ask is how a department answers the same question twice and disagrees with itself.

Answering one

orgabot organization department service respond acme svcreq_0001 \
  --as-role controller --evidence document:s3://close/2026-07.pdf \
  verdict=clean

A response cites the evidence kinds the contract requires, or it is refused. That is the whole point: a department closes a request by pointing at something, not by asserting the outcome.

A response is validated against the contract version the request was made under, not the current one. The requester agreed to those terms, and a version published in between must not demand fields nobody asked for. Answering twice is refused rather than silently overwriting evidence somebody already acted on.

Obligations and escalation

orgabot organization department service requests acme accounting
orgabot organization department service escalate acme svcreq_0001

Each open request reports on_time, overdue, or escalated against the windows in its own contract version. A request whose age cannot be computed reports unknown rather than on time: a request nobody can age is exactly the one that sits forever.

Escalating something still inside its window is refused, because escalating on-time work teaches everybody to ignore escalations. Escalating twice does not escalate twice.

A contract grants nothing

Publishing a service creates no connector, no grant, no capability slot, and no credential, and neither does requesting or answering one. Being on a handler list is not permission: the role still needs its own separately governed access to do the work.

This is worth stating plainly because a service contract is the most natural place to accidentally build a second authority system. "The contract says this role handles payments" is a sentence that could easily come to mean "this role may act on payments". It does not.

Versions

A contract is versioned and never edited in place. A change publishes a new version and retires the previous one, which stays readable so a six-week-old request still describes the terms it was made under rather than today's.