@agentplat/mesh-protocol 0.3.0-alpha.1 → 0.3.0-alpha.3

package/README.md

@@ -2,12 +2,27 @@
 
 Closed, bounded and transport-neutral wire contracts for AgentPlat Mesh peers.
 
-The Alpha 1 implementation provides:
+The implementation provides:
 
 - strict UTF-8 and JSON parsing that rejects duplicate decoded keys, malformed
   Unicode, ambiguous syntax and documents outside explicit structural limits;
 - deterministic JSON canonicalization for hashing and signing;
 - closed-schema validation for `peer.hello`, `peer.ping` and `peer.ping_ack`;
+- closed, bounded Alpha 2 discovery and capability records for `peer.card`,
+  `peer.goodbye`, `capability.advertise` and `capability.withdraw`;
+- closed, bounded Alpha 2 Objective records for `objective.announce`,
+  `objective.revise` and `objective.cancel`;
+- closed, bounded Alpha 2 Work Offer and Work Bid records for `work.offer` and
+  `work.bid`;
+- closed, bounded Alpha 2 award-response records for `work.award`,
+  `work.accept` and `work.decline`;
+- closed, bounded Alpha 2 execution records for `work.progress`,
+  `work.checkpoint` and `work.result`;
+- closed, bounded Alpha 2 Work Release and Work Cancel records for
+  `work.release` and `work.cancel`;
+- a closed, bounded Alpha 2 Lease Renewal record for `lease.renew`;
+- a closed, bounded Alpha 2 Lease Takeover Proposal record for
+  `lease.takeover_proposal`;
 - exact representations for message IDs, SHA-256 payload digests and Ed25519
   proofs;
 - receiver-context checks for tenant and Mesh scope, audience, freshness and
@@ -31,5 +46,283 @@ keys, verify signatures, perform replay admission, or mutate peer state. Those
 are separate stages so callers cannot confuse structural validity with
 cryptographic authenticity or local acceptance.
 
+Evidence, trust and peer-sync message families remain reserved until their
+closed payload contracts are implemented. They fail explicitly rather than
+entering a generic payload path. Implemented Objective, Work, Lease Renewal,
+Lease Takeover Proposal, Lease Vote and Lease Certificate records parse, sign
+and verify structurally, but remain explicitly unsupported at the Mesh runtime
+boundary until their reducers and state authorization are implemented.
+
+## Frozen limits
+
+Protocol v0 applies these structural limits before a payload can enter a
+reducer:
+
+| Limit                                  |             Maximum |
+| -------------------------------------- | ------------------: |
+| Decompressed envelope                  | 262,144 UTF-8 bytes |
+| Payload                                | 196,608 UTF-8 bytes |
+| Nesting depth                          |                  32 |
+| Total object keys / keys in one object |         2,048 / 256 |
+| Total array items / items in one array |       4,096 / 1,024 |
+| One string                             |  65,536 UTF-8 bytes |
+| Extensions / critical extensions       |              16 / 8 |
+| Identifier                             |     256 UTF-8 bytes |
+| Envelope lifetime                      |          10 minutes |
+| Clock-skew allowance                   |           2 minutes |
+| Replay window                          |     2,048 sequences |
+
+The implemented Alpha 2 discovery and capability payloads additionally freeze
+these narrower limits:
+
+| Field                                          | Rule                                                                                                                        |
+| ---------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| `protocolVersions`                             | 1–8 sorted unique non-negative safe integers and must include `0`                                                           |
+| Peer Card transport hints                      | At most 8 sorted unique non-empty strings; 2,048 UTF-8 bytes each and 8,192 bytes in aggregate                              |
+| Peer Card capability IDs                       | At most 32 sorted unique identifiers                                                                                        |
+| Capability key                                 | Non-empty; at most 4,096 UTF-8 bytes                                                                                        |
+| Capability version and optional variant        | Non-empty; at most 128 UTF-8 bytes each                                                                                     |
+| Input or output media types                    | At most 16 sorted unique non-empty strings per collection; 128 UTF-8 bytes each                                             |
+| Capability attributes                          | At most 32 entries; non-empty keys up to 128 UTF-8 bytes, non-empty values up to 1,024 bytes, and 16,384 bytes in aggregate |
+| Peer Card or capability-advertisement validity | Greater than zero and at most exactly 24 hours                                                                              |
+
+Every collection marked sorted and unique uses ascending lexicographic order
+over UTF-16 code units, matching the JCS/RFC 8785 property-name ordering rule.
+This is intentionally not Unicode code-point order; duplicate adjacent values
+are rejected.
+
+Envelope TTL is 30 seconds for `peer.ping` and `peer.ping_ack`, 60 seconds for
+`peer.goodbye`, and 120 seconds for `peer.hello`, `peer.card`,
+`capability.advertise` and `capability.withdraw`. These family limits are also
+bounded by the global ten-minute maximum.
+
+Work Release and Work Cancel envelopes have a two-minute TTL. Release is a
+closed `owner`/`assignee` authority and `reoffer`/`close` disposition pair;
+assignee release must be sent before its declared lease expiry. Cancel is a
+closed `award_pending` branch without `acceptanceId` or `active` branch with
+one. These are structural limits only; local state determines recipients,
+authority, terminality, idempotency and accounting.
+
+Lease Renewal envelopes have a 30-second TTL and must expire no later than the
+currently declared lease. A renewal self-binds the assignee, requires direct
+delivery and extends the declared expiry by a positive duration of at most 24
+hours. The accepted Objective may impose a lower duration and renewal count.
+
+Lease Takeover Proposal envelopes have a one-minute TTL. They require one direct
+peer audience, mandatory causation and Objective-header equality. The trusted
+receiver clock and accepted Objective policy—not sender-declared time—determine
+whether lease expiry plus recovery grace has elapsed.
+
+Lease Vote envelopes also have a one-minute TTL. They self-bind the witness,
+require direct delivery and Objective-header equality, and causally name the
+accepted takeover proposal they endorse. Witness membership and vote
+uniqueness require accepted local state.
+
+Lease Certificate envelopes have a one-minute TTL and self-bind their
+assembler. They carry between two and 32 sorted unique vote IDs, require direct
+delivery, Objective-header equality and proposal causation. The accepted
+Objective determines the actual threshold.
+
+Alpha 2 domain-limit, ordering, validity, self-binding and predecessor
+violations return `invalid_payload`. Envelope lifetime violations return
+`invalid_lifetime`; generic parser structural-limit violations return
+`structural_limit_exceeded`.
+
+## Objective limits
+
+Objective documents are complete replacements: announce is revision 1 with no
+envelope causation ID; revise is revision 2 or greater, names a different
+`previousObjectiveDocumentId`, and requires envelope `causationId`; cancel names
+the current document and revision and also requires envelope `causationId`.
+The envelope `causationId` is a message ID, not a substitute for the payload's
+previous-document ID. All three messages require an envelope `objectiveId` that
+exactly matches the payload. Document issuers must self-bind to the sender.
+Structural acceptance of `contentReference` does not authorize retrieval;
+issuer authority, reference authorization and current-revision checks require
+accepted local state and remain outside the protocol parser.
+
+| Field                        | Rule                                                                                                                                           |
+| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| Summary or content reference | Exactly one non-empty representation; each at most 4,096 UTF-8 bytes                                                                           |
+| Success criteria             | 1–32 non-empty strings, 4,096 UTF-8 bytes each and 16,384 bytes in aggregate                                                                   |
+| Permitted capability keys    | 1–32 sorted unique non-empty strings, 4,096 UTF-8 bytes each                                                                                   |
+| Work / concurrency           | Work items 1–1,000,000; concurrency 1 through work-item maximum                                                                                |
+| Budget units                 | Non-negative safe integer                                                                                                                      |
+| Timers                       | Bid window at most 1 hour; acceptance at most 15 minutes; lease at most 24 hours; recovery grace at most 1 hour; each must fit within validity |
+| Lease renewals               | Safe integer 0–100                                                                                                                             |
+| Recovery witnesses           | 3–32 sorted unique identifiers and strict-majority threshold                                                                                   |
+| Authorized observers         | Optional, at most 32 sorted unique identifiers                                                                                                 |
+| Objective validity           | Greater than zero and at most exactly 30 days                                                                                                  |
+
+Objective announce and revise have a five-minute envelope TTL; cancel has a
+two-minute TTL. Objective scope, binding, closure, ordering, revision,
+causation, timer and limit violations reject with `invalid_payload`; their TTL
+violations reject with `invalid_lifetime`.
+
+## Work Offer and Bid limits
+
+Work Offers name an immutable Objective document and work-item revision. The
+first attempt has no predecessor or envelope causation; later attempts require
+both and must name a different `previousOfferId`. Offers self-bind their owner
+to the envelope sender and may target one peer or the `work` topic. Work Bids
+name one Offer, self-bind their bidder to the sender, require causation, and
+must be addressed directly to the named owner. Bid revision 1 has no predecessor;
+later revisions require a different `previousBidId`.
+
+| Field                        | Rule                                                                                                                                                                                |
+| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Required capability keys     | 1–32 sorted unique non-empty strings, at most 4,096 UTF-8 bytes each                                                                                                                |
+| Matching attributes          | At most 32 entries; non-empty keys up to 128 UTF-8 bytes, non-empty values up to 1,024 bytes, and 16,384 bytes in aggregate                                                         |
+| Input summary or reference   | Exactly one non-empty representation; each at most 4,096 UTF-8 bytes                                                                                                                |
+| Completion criteria          | 1–32 non-empty strings, at most 4,096 UTF-8 bytes each and 16,384 bytes in aggregate                                                                                                |
+| Bid assumptions              | 0–32 non-empty strings, at most 4,096 UTF-8 bytes each and 16,384 bytes in aggregate                                                                                                |
+| Reservation and budget units | Budget values are non-negative safe integers; capacity reservation is a safe integer from 1 through 1,000,000                                                                       |
+| Offer deadlines              | `sentAt < bidDeadline < workDeadline`; bid deadline is at most 1 hour after send, work deadline at most 30 days after send, and envelope expiry must not exceed bid deadline        |
+| Bid deadlines                | `sentAt < bidExpiresAt <= bidDeadline < expectedCompletionAt <= workDeadline`; the same one-hour bid and 30-day work horizons apply, and envelope expiry must not exceed bid expiry |
+
+Offer and Bid envelope TTL is two minutes. Structural validation does not decide
+whether an Objective revision is current, a Work Item is current, an offer
+attempt supersedes another offer, a capability advertisement is accepted, a
+bid has capacity or budget authority, or deadlines and reservations are valid
+against accepted local state. Those checks require reducer authorization state
+and remain deferred.
+
+## Work Award, Accept and Decline limits
+
+An Award names one Offer and selected Bid and self-binds the owner sender. Any
+direct peer audience is structurally valid; whether it is the assignee or a
+witness is a local-state check. It carries an assignment epoch,
+assignment-authority ID and fencing token. The normal `authorityKind: "award"`
+branch requires both IDs to equal `awardId` and forbids recovery references. The
+`authorityKind: "recovery_certificate"` branch requires `recoveryCertificateId`
+and requires both IDs to equal that certificate; an optional resume checkpoint
+is structural metadata only.
+
+Accept and Decline each name the Award and self-bind the assignee sender.
+Accept accepts any direct peer audience structurally; owner-or-witness
+authorization is stateful. Decline is structurally directed to the owner. Both
+require an envelope causation ID. Resolving Award causation to the selected Bid
+envelope, and response causation to the accepted Award envelope, requires the
+local causal journal and is stateful. All three records bind the envelope
+Objective ID to the payload Objective ID.
+
+| Field            | Rule                                                                                       |
+| ---------------- | ------------------------------------------------------------------------------------------ |
+| Owner epoch      | Positive safe integer; frozen at `1` for this protocol slice                               |
+| Assignment epoch | Positive safe integer; recovery authority requires epoch `2` or greater                    |
+| Award time order | `sentAt <= leaseStartsAt < acceptanceDeadline <= leaseExpiresAt <= workDeadline`           |
+| Award windows    | Acceptance window at most 15 minutes; lease at most 24 hours; work horizon at most 30 days |
+| Award expiry     | At most two minutes and no later than `acceptanceDeadline`                                 |
+| Response time    | `sentAt < acceptanceDeadline`; expiry at most two minutes and no later than that deadline  |
+
+These are structural contracts only. Selection of a current bid, current owner
+and revision, budget reservation, acceptance uniqueness, deadline observation,
+causal-reference resolution, and recovery-certificate acceptance all require
+local state and remain deferred.
+
+## Work Progress, Checkpoint and Result limits
+
+Execution records self-bind the assignee sender, require a direct peer audience
+and causation, and bind Objective and Work Item revisions, accepted assignment
+IDs, epoch, authority token and lease expiry. Each record has a stable domain
+ID independent of the envelope message ID.
+
+| Field              | Rule                                                                                            |
+| ------------------ | ----------------------------------------------------------------------------------------------- |
+| Owner epoch        | Positive safe integer; frozen at `1` for this protocol slice                                    |
+| Assignment binding | Positive epoch; `assignmentAuthorityId` and `fencingToken` must be identical identifiers        |
+| Progress           | Positive sequence and non-empty summary of at most 4,096 UTF-8 bytes; checkpoint ID is optional |
+| Checkpoint         | Positive sequence, canonical SHA-256 digest and exactly one summary or reference                |
+| Checkpoint parent  | Sequence `1` omits a parent; later sequences require a different `previousCheckpointId`         |
+| Result             | Canonical SHA-256 digest, optional checkpoint ID and exactly one summary or reference           |
+| Content            | Summaries and references are non-empty and at most 4,096 UTF-8 bytes                            |
+| Execution expiry   | At most five minutes, strictly after `sentAt` and no later than the signed `leaseExpiresAt`     |
+
+The structural parser does not prove that causation resolves to the matching
+accepted `work.accept`, that the recipient is an authorized owner, observer or
+witness, or that the assignment, epoch, authority, token, lease and checkpoint
+head are current. It also does not enforce progress ordering or result
+uniqueness. Those checks require accepted local state and remain deferred to
+the Mesh runtime reducer boundary.
+
+## Lease Renewal limits
+
+Lease Renewal carries the accepted assignment authority plus
+`leaseRenewalId`, `leaseRenewalSequence` and `renewedLeaseExpiresAt`. The
+existing `leaseExpiresAt` is the current lease that limits delivery; the renewed
+timestamp is the proposed successor. Sequence `1` omits
+`previousLeaseRenewalId`; later sequences require a different predecessor ID.
+
+The sender self-binds to `assigneePeerId`, the audience is one direct peer, the
+envelope Objective ID equals the payload Objective ID, and causation is
+required. The first accepted renewal resolves causation to `work.accept`; later
+renewals resolve it to the immediately preceding `lease.renew` envelope for
+that recipient. Recipient authorization, exact predecessor and sequence,
+current assignment and lease, Work deadline, Objective duration/count policy,
+terminal state and idempotency remain stateful reducer checks.
+
+## Lease Takeover Proposal limits
+
+Lease Takeover Proposal carries the accepted assignment authority and current
+lease expiry plus a stable `takeoverProposalId`. It identifies the self-bound
+`proposerPeerId`, a closed `candidate` or `witness` `proposalAuthority`, the
+different `proposedAssigneePeerId`, and exactly the next declared assignment
+epoch. It does not propose a fencing token; an accepted recovery certificate's
+stable ID becomes that token later.
+
+`leaseRenewalSequence` is `0` for the initial accepted lease and omits
+`latestLeaseRenewalId`. Values `1` through `100` require that stable renewal ID.
+Causation resolves to the accepted `work.accept` for sequence `0`, or to the
+latest accepted `lease.renew` envelope for the receiving witness.
+
+The parser enforces closed fields, role consistency, direct delivery, mandatory
+causation, Objective equality and the one-minute TTL. It does not establish that
+the lease head is accepted or expired, recovery grace elapsed, the proposer and
+candidate are eligible, the recipient is a configured witness, or the Work Item
+is current and non-terminal. Those checks require accepted local state and a
+trusted receiver clock. A valid proposal records recovery intent only; it does
+not advance the epoch, grant execution authority, change fencing or reserve
+budget.
+
+## Lease Vote limits
+
+Lease Vote is an affirmative witness endorsement of one accepted takeover
+proposal. Its closed payload contains a stable `leaseVoteId`, the logical
+`takeoverProposalId`, the self-bound `witnessPeerId` and the Objective ID. It
+does not repeat candidate, Work Item, assignment, lease, epoch or fencing
+fields; those are resolved from the causally accepted proposal so that two
+signed snapshots cannot disagree.
+
+The audience is one direct peer, the envelope Objective ID equals the payload
+Objective ID, causation is required and TTL is at most one minute. The parser
+does not establish that causation names the matching accepted proposal, the
+sender belongs to its fixed witness set, the recipient is a recovery
+participant, or the witness has not already endorsed another proposal for the
+same Work Item revision and proposed epoch. Those are stateful reducer checks.
+A vote alone does not advance an epoch, change fencing, grant execution
+authority, activate a candidate or mutate budget.
+
+## Lease Certificate limits
+
+Lease Certificate references one accepted takeover proposal and the witness
+votes that certify it. Its closed payload contains a stable `certificateId`,
+the self-bound `certificateAssemblerPeerId`, `takeoverProposalId`, between two
+and 32 sorted unique `leaseVoteIds`, and the Objective ID. It does not repeat
+candidate, Work Item, assignment, lease, epoch or fencing fields; the accepted
+proposal is their canonical source.
+
+The audience is one direct peer, the envelope Objective ID equals the payload
+Objective ID, causation names the proposal envelope and TTL is at most one
+minute. The parser does not prove that the proposal or votes are accepted, that
+the votes endorse the same proposal, come from distinct configured witnesses
+or satisfy the Objective threshold, or that the assembler and recipient are
+authorized. Those are stateful reducer checks.
+
+After stateful acceptance, `certificateId` becomes the next assignment
+authority ID and fencing token, and the Work Item enters recovery. The
+certificate does not itself grant execution authority or activate the
+candidate; that requires the existing owner-issued recovery award and
+acceptance flow.
+
 Importing the package performs no parsing, key resolution, network or storage
 operation.

package/dist/contracts.d.ts

@@ -47,6 +47,20 @@ export interface PeerHelloPayload {
     readonly peerCardId: string;
     readonly cardRevision: number;
 }
+/** Publishes one bounded revision of a peer's discovery card. */
+export interface PeerCardPayload {
+    readonly type: 'peer.card';
+    readonly peerCardId: string;
+    readonly cardRevision: number;
+    readonly subjectPeerId: string;
+    readonly instanceId: string;
+    readonly protocolVersions: readonly number[];
+    readonly transportHints: readonly string[];
+    readonly capabilityIds: readonly string[];
+    readonly validFrom: string;
+    readonly validUntil: string;
+    readonly previousPeerCardId?: string;
+}
 /** Requests a direct liveness response from the audience peer. */
 export interface PeerPingPayload {
     readonly type: 'peer.ping';
@@ -55,8 +69,327 @@ export interface PeerPingPayload {
 export interface PeerPingAckPayload {
     readonly type: 'peer.ping_ack';
 }
-/** Payload subset implemented by the Alpha 1 vertical slice. */
-export type MeshMessagePayload = PeerHelloPayload | PeerPingPayload | PeerPingAckPayload;
+/** Retires the sender's current peer card and process instance. */
+export interface PeerGoodbyePayload {
+    readonly type: 'peer.goodbye';
+    readonly peerCardId: string;
+    readonly cardRevision: number;
+    readonly instanceId: string;
+}
+/** Publishes one bounded revision of a peer-owned capability. */
+export interface CapabilityAdvertisePayload {
+    readonly type: 'capability.advertise';
+    readonly advertisementId: string;
+    readonly capabilityId: string;
+    readonly capabilityRevision: number;
+    readonly ownerPeerId: string;
+    readonly capabilityKey: string;
+    readonly version: string;
+    readonly variant?: string;
+    readonly inputMediaTypes: readonly string[];
+    readonly outputMediaTypes: readonly string[];
+    readonly attributes: Readonly<Record<string, string>>;
+    readonly validFrom: string;
+    readonly validUntil: string;
+    readonly maximumConcurrency?: number;
+    readonly maximumPayloadBytes?: number;
+    readonly previousAdvertisementId?: string;
+}
+/** Withdraws one specific advertised revision of a capability. */
+export interface CapabilityWithdrawPayload {
+    readonly type: 'capability.withdraw';
+    readonly capabilityId: string;
+    readonly capabilityRevision: number;
+    readonly advertisementId: string;
+}
+/** Fields shared by complete Objective announcement and revision documents. */
+export interface ObjectiveDocumentFields {
+    readonly objectiveDocumentId: string;
+    readonly objectiveId: string;
+    readonly objectiveRevision: number;
+    readonly issuerPeerId: string;
+    readonly successCriteria: readonly string[];
+    readonly permittedCapabilityKeys: readonly string[];
+    readonly maximumWorkItems: number;
+    readonly maximumConcurrentAssignments: number;
+    readonly maximumBudgetUnits: number;
+    readonly bidWindowMs: number;
+    readonly acceptanceWindowMs: number;
+    readonly maximumLeaseDurationMs: number;
+    readonly recoveryGraceMs: number;
+    readonly maximumLeaseRenewals: number;
+    readonly recoveryWitnessPeerIds: readonly string[];
+    readonly recoveryWitnessThreshold: number;
+    readonly validFrom: string;
+    readonly validUntil: string;
+    readonly authorizedObserverPeerIds?: readonly string[];
+}
+/** Exactly one inline summary or external content reference. */
+export type ObjectiveDocumentContent = {
+    readonly summary: string;
+    readonly contentReference?: never;
+} | {
+    readonly summary?: never;
+    readonly contentReference: string;
+};
+/** Complete first revision of an objective issued to the mesh. */
+export type ObjectiveAnnouncePayload = ObjectiveDocumentFields & ObjectiveDocumentContent & {
+    readonly type: 'objective.announce';
+};
+/** Complete replacement revision of an existing objective document. */
+export type ObjectiveRevisePayload = ObjectiveDocumentFields & ObjectiveDocumentContent & {
+    readonly type: 'objective.revise';
+    readonly previousObjectiveDocumentId: string;
+};
+/** Cancels one specific objective document revision. */
+export interface ObjectiveCancelPayload {
+    readonly type: 'objective.cancel';
+    readonly cancellationId: string;
+    readonly objectiveId: string;
+    readonly objectiveRevision: number;
+    readonly objectiveDocumentId: string;
+}
+/** Fields shared by every complete work offer. */
+export interface WorkOfferFields {
+    readonly offerId: string;
+    readonly objectiveId: string;
+    readonly objectiveDocumentId: string;
+    readonly objectiveRevision: number;
+    readonly workItemId: string;
+    readonly workItemRevision: number;
+    readonly ownerPeerId: string;
+    readonly ownerEpoch: number;
+    readonly offerAttempt: number;
+    readonly previousOfferId?: string;
+    readonly requiredCapabilityKeys: readonly string[];
+    readonly matchingAttributes: Readonly<Record<string, string>>;
+    readonly completionCriteria: readonly string[];
+    readonly budgetReservationUnits: number;
+    readonly bidDeadline: string;
+    readonly workDeadline: string;
+}
+/** Exactly one inline work input summary or external content reference. */
+export type WorkOfferInput = {
+    readonly inputSummary: string;
+    readonly inputReference?: never;
+} | {
+    readonly inputSummary?: never;
+    readonly inputReference: string;
+};
+/** Offers one bounded work item for capability-based bidding. */
+export type WorkOfferPayload = WorkOfferFields & WorkOfferInput & {
+    readonly type: 'work.offer';
+};
+/** Proposes one capacity and budget reservation for an accepted work offer. */
+export interface WorkBidPayload {
+    readonly type: 'work.bid';
+    readonly bidId: string;
+    readonly bidRevision: number;
+    readonly previousBidId?: string;
+    readonly offerId: string;
+    readonly objectiveId: string;
+    readonly objectiveDocumentId: string;
+    readonly objectiveRevision: number;
+    readonly workItemId: string;
+    readonly workItemRevision: number;
+    readonly ownerPeerId: string;
+    readonly ownerEpoch: number;
+    readonly offerAttempt: number;
+    readonly bidderPeerId: string;
+    readonly advertisementId: string;
+    readonly capabilityId: string;
+    readonly capabilityRevision: number;
+    readonly capacityReservationUnits: number;
+    readonly budgetUnits: number;
+    readonly bidDeadline: string;
+    readonly workDeadline: string;
+    readonly expectedCompletionAt: string;
+    readonly bidExpiresAt: string;
+    readonly assumptions: readonly string[];
+}
+/** Fields common to both fresh awards and recovery-certified assignments. */
+export interface WorkAwardFields {
+    readonly type: 'work.award';
+    readonly awardId: string;
+    readonly offerId: string;
+    readonly bidId: string;
+    readonly bidRevision: number;
+    readonly objectiveId: string;
+    readonly objectiveDocumentId: string;
+    readonly objectiveRevision: number;
+    readonly workItemId: string;
+    readonly workItemRevision: number;
+    readonly ownerPeerId: string;
+    readonly ownerEpoch: number;
+    readonly offerAttempt: number;
+    readonly assigneePeerId: string;
+    readonly assignmentEpoch: number;
+    readonly assignmentAuthorityId: string;
+    readonly fencingToken: string;
+    readonly budgetReservationUnits: number;
+    readonly workDeadline: string;
+    readonly leaseStartsAt: string;
+    readonly leaseExpiresAt: string;
+    readonly acceptanceDeadline: string;
+}
+/** Assigns work under either the original award or recovery authority. */
+export type WorkAwardPayload = (WorkAwardFields & {
+    readonly authorityKind: 'award';
+    readonly recoveryCertificateId?: never;
+    readonly resumeCheckpointId?: never;
+}) | (WorkAwardFields & {
+    readonly authorityKind: 'recovery_certificate';
+    readonly recoveryCertificateId: string;
+    readonly resumeCheckpointId?: string;
+});
+/** Fields echoed by an assignee when responding to one assignment. */
+export interface WorkAssignmentResponseFields {
+    readonly awardId: string;
+    readonly objectiveId: string;
+    readonly objectiveDocumentId: string;
+    readonly objectiveRevision: number;
+    readonly workItemId: string;
+    readonly workItemRevision: number;
+    readonly ownerPeerId: string;
+    readonly ownerEpoch: number;
+    readonly assigneePeerId: string;
+    readonly assignmentEpoch: number;
+    readonly assignmentAuthorityId: string;
+    readonly fencingToken: string;
+    readonly acceptanceDeadline: string;
+}
+/** Accepts one assignment before its bounded response deadline. */
+export interface WorkAcceptPayload extends WorkAssignmentResponseFields {
+    readonly type: 'work.accept';
+    readonly acceptanceId: string;
+}
+/** Declines one assignment before its bounded response deadline. */
+export interface WorkDeclinePayload extends WorkAssignmentResponseFields {
+    readonly type: 'work.decline';
+    readonly declineId: string;
+}
+/** Assignment authority echoed by every assignment lifecycle record. */
+export interface WorkAssignmentAuthorityFields {
+    readonly objectiveId: string;
+    readonly objectiveDocumentId: string;
+    readonly objectiveRevision: number;
+    readonly workItemId: string;
+    readonly workItemRevision: number;
+    readonly ownerPeerId: string;
+    readonly ownerEpoch: number;
+    readonly assigneePeerId: string;
+    readonly awardId: string;
+    readonly assignmentEpoch: number;
+    readonly assignmentAuthorityId: string;
+    readonly fencingToken: string;
+    readonly leaseExpiresAt: string;
+}
+/** Accepted assignment authority echoed by every execution record. */
+export interface WorkExecutionAuthorityFields extends WorkAssignmentAuthorityFields {
+    readonly acceptanceId: string;
+}
+/** Reports bounded incremental progress under one accepted assignment. */
+export interface WorkProgressPayload extends WorkExecutionAuthorityFields {
+    readonly type: 'work.progress';
+    readonly progressId: string;
+    readonly progressSequence: number;
+    readonly progressSummary: string;
+    readonly checkpointId?: string;
+}
+/** Exactly one inline checkpoint summary or external content reference. */
+export type WorkCheckpointContent = {
+    readonly checkpointSummary: string;
+    readonly checkpointReference?: never;
+} | {
+    readonly checkpointSummary?: never;
+    readonly checkpointReference: string;
+};
+/** Persists a content-addressed checkpoint under one accepted assignment. */
+export type WorkCheckpointPayload = WorkExecutionAuthorityFields & WorkCheckpointContent & {
+    readonly type: 'work.checkpoint';
+    readonly checkpointId: string;
+    readonly checkpointSequence: number;
+    readonly previousCheckpointId?: string;
+    readonly checkpointDigest: string;
+};
+/** Exactly one inline result summary or external content reference. */
+export type WorkResultContent = {
+    readonly resultSummary: string;
+    readonly resultReference?: never;
+} | {
+    readonly resultSummary?: never;
+    readonly resultReference: string;
+};
+/** Publishes a content-addressed result under one accepted assignment. */
+export type WorkResultPayload = WorkExecutionAuthorityFields & WorkResultContent & {
+    readonly type: 'work.result';
+    readonly resultId: string;
+    readonly resultDigest: string;
+    readonly checkpointId?: string;
+};
+/** Releases an active assignment under owner or assignee authority. */
+export interface WorkReleasePayload extends WorkExecutionAuthorityFields {
+    readonly type: 'work.release';
+    readonly releaseId: string;
+    readonly releaseAuthority: 'owner' | 'assignee';
+    readonly releaseDisposition: 'reoffer' | 'close';
+}
+/** Cancels either a pending award or an active accepted assignment. */
+export type WorkCancelPayload = WorkAssignmentAuthorityFields & {
+    readonly type: 'work.cancel';
+    readonly cancellationId: string;
+} & ({
+    readonly assignmentState: 'award_pending';
+    readonly acceptanceId?: never;
+} | {
+    readonly assignmentState: 'active';
+    readonly acceptanceId: string;
+});
+/** Extends one accepted assignment lease without changing its authority. */
+export interface LeaseRenewPayload extends WorkExecutionAuthorityFields {
+    readonly type: 'lease.renew';
+    readonly leaseRenewalId: string;
+    readonly leaseRenewalSequence: number;
+    readonly previousLeaseRenewalId?: string;
+    readonly renewedLeaseExpiresAt: string;
+}
+/** Assignment and lease snapshot shared by candidate and witness proposals. */
+export interface LeaseTakeoverProposalFields extends WorkExecutionAuthorityFields {
+    readonly type: 'lease.takeover_proposal';
+    readonly takeoverProposalId: string;
+    readonly proposerPeerId: string;
+    readonly proposedAssigneePeerId: string;
+    readonly proposedAssignmentEpoch: number;
+    readonly leaseRenewalSequence: number;
+    readonly latestLeaseRenewalId?: string;
+}
+/** Proposes the next assignment epoch after one accepted lease expires. */
+export type LeaseTakeoverProposalPayload = LeaseTakeoverProposalFields & ({
+    readonly proposalAuthority: 'candidate';
+    readonly candidateConsentProposalId?: never;
+} | {
+    readonly proposalAuthority: 'witness';
+    readonly candidateConsentProposalId: string;
+});
+/** Endorses one accepted takeover proposal under configured witness authority. */
+export interface LeaseVotePayload {
+    readonly type: 'lease.vote';
+    readonly leaseVoteId: string;
+    readonly takeoverProposalId: string;
+    readonly witnessPeerId: string;
+    readonly objectiveId: string;
+}
+/** Certifies one takeover proposal from a bounded set of witness votes. */
+export interface LeaseCertificatePayload {
+    readonly type: 'lease.certificate';
+    readonly certificateId: string;
+    readonly certificateAssemblerPeerId: string;
+    readonly takeoverProposalId: string;
+    readonly leaseVoteIds: readonly string[];
+    readonly objectiveId: string;
+}
+/** Structurally implemented protocol payload subset. */
+export type MeshMessagePayload = PeerHelloPayload | PeerCardPayload | PeerPingPayload | PeerPingAckPayload | PeerGoodbyePayload | CapabilityAdvertisePayload | CapabilityWithdrawPayload | ObjectiveAnnouncePayload | ObjectiveRevisePayload | ObjectiveCancelPayload | WorkOfferPayload | WorkBidPayload | WorkAwardPayload | WorkAcceptPayload | WorkDeclinePayload | WorkProgressPayload | WorkCheckpointPayload | WorkResultPayload | WorkReleasePayload | WorkCancelPayload | LeaseRenewPayload | LeaseTakeoverProposalPayload | LeaseVotePayload | LeaseCertificatePayload;
 /** Shared fields that participate in envelope identity and signing. */
 export interface MeshEnvelopeHeader<TPayload extends MeshMessagePayload = MeshMessagePayload> {
     readonly protocol: typeof MESH_PROTOCOL;