Federated Answer Procurement Lifecycle Artifacts

Based on:

• doc/project/30-stories/story-001-swarm-node-onboarding.md
• doc/project/30-stories/story-004-pod-client-onboarding.md
• doc/project/40-proposals/003-question-envelope-and-answer-channel.md
• doc/project/40-proposals/004-human-origin-flags-and-operator-participation.md
• doc/project/40-proposals/005-operator-participation-room-policy-profiles.md
• doc/project/40-proposals/008-transcription-monitors-and-public-vaults.md
• doc/project/40-proposals/009-communication-exposure-modes.md

Status

Proposed (Draft)

Date

2026-03-22

Executive Summary

This proposal defines the missing machine-readable lifecycle artifacts for federated answer procurement.

The key decision is simple:

1. the same procurement lifecycle should work for full-node, hybrid, and pod-client participation,
2. the lifecycle should be expressed as a small set of explicit artifacts rather than implicit chat history,
3. collaborative answer rooms and paid single-responder execution should remain linkable through shared identifiers instead of becoming separate universes,
4. provenance, settlement, and publication policy should remain visible at the data boundary.
5. payment settlement must remain rail-neutral at the protocol core so the project does not need to start as a crypto-asset operator.

Context and Problem Statement

The current corpus already covers most of the conceptual pieces:

• question envelopes and answer rooms,
• exposure modes,
• room policy profiles,
• human-origin semantics,
• transcript monitoring,
• pod-backed participation.

What remains underspecified is the concrete lifecycle that moves a request through:

• publication,
• offer collection,
• selection,
• contract formation,
• answer delivery,
• receipt and audit.

Without explicit artifacts:

• different node profiles will improvise incompatible payloads,
• deterministic validation becomes difficult,
• settlement and provenance become chat-convention rather than contract,
• later transcript, archival, and reputation layers inherit ambiguity.

Goals

• Define a minimal interoperable lifecycle for federated answer procurement.
• Reuse the same artifact set across full-node, hybrid, and pod-client.
• Keep collaborative room mode and price-bound procurement mode linkable.
• Make settlement and receipts explicit.
• Preserve provenance and human-origin semantics at the response boundary.
• Keep the trusted core small enough to be implementable on multiple runtimes.

Non-Goals

• This proposal does not freeze the exact offer-scoring algorithm.
• This proposal does not define the full reputation backend.
• This proposal does not define the full dispute or appeal workflow.
• This proposal does not define final cryptographic signature container formats.
• This proposal does not mandate on-chain or crypto-native settlement.

Decision

Orbiplex should adopt five explicit lifecycle artifacts as the v1 procurement core:

1. question-envelope
2. procurement-offer
3. procurement-contract
4. procurement-receipt
5. response-envelope

These artifacts are sufficient to represent the happy path for:

• collaborative answer discovery,
• narrowing to a selected responder,
• optional paid settlement,
• provenance-rich answer return.

The same question/id remains the common thread between room discussion, procurement, transcript material, and final response.

Proposed Lifecycle

1. question-envelope

Purpose:

• publish a signed request on the event layer,
• declare exposure mode and response channel,
• express responder filters and procurement intent,
• open the room-level context for later discussion.

This artifact belongs to the asking side and is the canonical opening move.

The baseline authored path may remain participant-scoped, but the lifecycle should also tolerate a pseudonymous question publication path where:

• sender/node-id still routes the envelope,
• author/nym identifies the visible author,
• the envelope carries attached nym-certificate,
• and the envelope body is signed by the nym key rather than by a directly disclosed participant identity.

2. procurement-offer

Purpose:

• let an eligible remote responder advertise terms,
• keep price, deadline, answer bounds, and specialization fit explicit,
• attach bounded reputation evidence without requiring the full answer yet.

This artifact lets the asking side compare offers deterministically.

3. procurement-contract

Purpose:

• record the selected responder and acceptance criteria,
• freeze payment terms and confirmation mode,
• bind the narrower execution path back to the original question and room.

This artifact is the line between offer comparison and accountable execution.

4. procurement-receipt

Purpose:

• record the outcome of the contract,
• preserve signatures or signature references of relevant actors,
• provide auditable closure for settlement, rejection, cancellation, or expiry.

This artifact is the settlement and audit anchor.

5. response-envelope

Purpose:

• deliver the accepted answer back to the local node or thin client,
• preserve responder, room, contract, and receipt references,
• surface confidence and human-origin semantics without requiring transcript parsing.

This artifact is the user-facing machine-readable result boundary.

For v1, response-envelope should remain participant-scoped rather than nym-authored:

• routing remains source/node-id,
• accountable authorship remains source/participant-id,
• and public pseudonymous presentation, if later needed, should stay additive rather than replacing participant accountability inside the settlement and audit boundary.

Identity and Participation Compatibility

The lifecycle must work across participation profiles.

full-node

The asking node is both the user-facing actor and the swarm-facing actor.

hybrid

The asking side may mix local execution with delegated execution, but the lifecycle artifacts remain the same.

pod-client

The serving node may publish and route on behalf of a hosted user, but the artifacts must preserve the distinction between:

• serving infrastructure actor,
• hosted participant,
• optional public-facing nym.

The artifact model therefore must tolerate delegated gateways without losing identity semantics.

Contract Boundaries

Shared identifiers

At minimum, the lifecycle should keep explicit links among:

• question/id
• room/id
• offer/id
• contract/id
• receipt/id
• response/id

Policy surfaces

The artifacts should carry enough information to derive or validate:

• exposure mode,
• room policy profile,
• procurement intent,
• confirmation mode,
• human-origin relevance,
• transcript eligibility decisions.

Settlement neutrality

The lifecycle must keep settlement semantics explicit without requiring one payment rail.

The v1 rule should be:

• contracts define amount, unit, and confirmation semantics,
• receipts record outcome and settlement reference,
• the protocol core stays neutral between:
• external invoicing,
• host-local ledger settlement,
• manual transfer,
• future specialized rails.

This keeps Orbiplex from binding early product scope to crypto-native operator duties.

Deliberate omissions from v1

The following remain intentionally outside the trusted core for now:

• full dispute and appeal state machine,
• full reputation aggregation model,
• transport-specific wrappers,
• final signature packaging standard,
• local sufficiency-check algorithm.

Minimal v1 Schema Set

The recommended v1 schema filenames are:

• question-envelope.v1.schema.json
• procurement-offer.v1.schema.json
• procurement-contract.v1.schema.json
• procurement-receipt.v1.schema.json
• response-envelope.v1.schema.json

These should become the canonical machine boundary for the procurement lifecycle.

MVP Implementation Profile

The hard-MVP implementation covers the selected-responder procurement slice of this proposal:

• question-envelope.v1, procurement-offer.v1, and response-envelope.v1 are synchronized into node/protocol/contracts and validated by schema-gate at daemon ingress.
• procurement-contract.v1 and procurement-receipt.v1 are synchronized protocol contracts and are materialized by the daemon as first-class committed records.
• The daemon collects offers, ranks them deterministically, selects one responder, forms one contract, accepts one response, and commits one receipt.
• Equal composite offer scores are resolved by the deterministic precedence tuple (lower price, earlier deadline, higher provider reputation, lexical offer/id).
• Zero-price execution uses the same contract/receipt join points without creating a settlement hold.
• Paid execution is settlement-aware: it creates local holds through the deployment ledger, then releases, refunds, freezes, expires, cancels, or records disputes through committed procurement facts.
• The host-owned service-order bridge derives a full schema-valid question-envelope.v1 plus procurement-offer.v1 pair for local marketplace execution instead of smuggling marketplace-specific fields into procurement wire contracts.
• selected-responder names the question exposure profile: the asker is opening a narrowed procurement path. single-responder names the offer execution mode: a responder proposes to execute the narrowed path alone rather than through a collaborative room.
• response-envelope.v1 may carry contract/id before receipt/id exists; the receipt is a later audit and settlement artifact produced by the procurement lifecycle.
• response-envelope.v1 carries both a composite confidence value and decomposed factors such as retrieval coverage and arbiter outcome. The composite is a convenience projection; the decomposed factors are the audit carrier.
• The current runtime gate is a daemon control-plane boundary: JSON artifacts are schema-gated before daemon decoding and the HTTP mutation surface still requires the local control token. Domain-level Ed25519 verification of participant and nym signatures remains a separate post-MVP trust-boundary step before these artifacts may be accepted directly from untrusted peers.

Still out of scope for this MVP slice:

• collaborative many-responder answer rooms,
• a general federated procurement event bus,
• a full dispute/appeal lifecycle beyond the current first-class dispute record,
• a dedicated procurement-contract projector when execution inspection and receipt joins are sufficient,
• final signature-container standardization and cryptographic verification across all participation profiles.

Trade-offs

1. Explicit artifacts vs simpler chat-only flow:
2. Benefit: interoperability, validation, auditability.
3. Cost: more schema and versioning surface.
4. Small core vs richer semantics:
5. Benefit: easier multi-runtime implementation.
6. Cost: retry, dispute, and reputation details still live outside the core.
7. Unified lifecycle across node profiles vs profile-specific shortcuts:
8. Benefit: lower coupling and easier migration between participation modes.
9. Cost: delegated pod flows still need some extra identity fields or wrappers.

Open Questions

No unresolved questions remain for this proposal slice. The decisions below record the approved defaults.

Resolved 2026-07-04:

1. Equal offer scores are resolved by a deterministic tuple: lower price, earlier deadline, higher provider reputation, then lexical offer/id.
2. response-envelope carries both composite confidence and decomposed factors such as retrieval coverage and arbiter outcome. The composite value is the convenience view; the factors are the audit view.
3. A future dispute-case artifact lives as a separate lifecycle family with references to the procurement receipt. The receipt remains a settlement artifact rather than the container for the whole dispute process.
4. The core artifact remains minimal for pod-client delegated publication. Transport-specific fields belong in transport wrappers outside the core artifact.

Next Actions

1. Keep the five v1 JSON Schemas as the canonical machine boundary for this lifecycle.
2. Extend positive and negative fixtures as new participation profiles become runtime surfaces.
3. Bind future offer-scoring and dispute proposals to these identifiers instead of inventing parallel payload families.
4. Add collaborative-room procurement tests only when the P003 room/event transport profile becomes an implementation target.
5. Add participant/nym signature verification before accepting procurement artifacts from peer-facing or otherwise untrusted ingress surfaces.
6. Add conformance fixtures for equal-score offer ranking that exercise each deterministic tiebreak level: price, deadline, provider reputation, and lexical offer/id.
7. Add the decomposed confidence-factor field family to response-envelope.v1; composite confidence remains a derived convenience view.

Tracking

ID	Feature	Status	Evidence
P011-01	v1 schema set for question, offer, contract, receipt, and response artifacts	done	Canonical schemas exist in doc/schemas/ and selected contracts are synchronized into node/protocol/contracts.
P011-02	Schema-gated daemon ingress for question, offer, and response artifacts	done	schema-gate validates question-envelope.v1, procurement-offer.v1, and response-envelope.v1 before daemon decoding.
P011-03	Deterministic selected-responder offer collection and ranking	done	Daemon tests cover deterministic offer scoring and priority-factor penalties.
P011-04	First-class procurement contracts and receipts	done	Contracts and receipts are committed through append-only daemon storage and exposed through execution/receipt inspection.
P011-05	Zero-price and paid settlement-aware closure	done	Runtime tests cover zero-price closure, paid acceptance, settlement receipts, expiry, cancel, and dispute persistence.
P011-06	Host-owned marketplace/service-order bridge into procurement	done	Service-order bridge derives schema-valid question and offer artifacts and preserves marketplace lineage outside procurement wire contracts.
P011-07	Collaborative many-responder room lifecycle	post-MVP	P003 room/event transport remains deferred; MVP uses selected-responder execution.
P011-08	Full dispute/appeal lifecycle	post-MVP	MVP persists first-class dispute records; broader appeal workflow remains a separate lifecycle family.