YieldFabric: substrate for the alignment economy
The thesis. YF as infrastructure for the alignment economy — humans build entangled joint wanting through AI-augmented conversation; the moment of agreement is the measurement event that collapses it into a realised deal. Five operational roles: reason · communicate · negotiate · structure · execute. Read this first.
An economy is a coordination technology for human alignment. YieldFabric is infrastructure for the alignment kind — where people build entangled joint wanting through AI-augmented conversation, and the moment of agreement is the measurement event that collapses it into a realised deal.
This page is the lens that explains why every other primitive in this site is shaped the way it is. Read it first. Every endpoint, every event, every state machine here implements one specific operational role in a single living process — the continuous discovery of new joint outcomes between humans whose wanting is reshaped by each other.
Background: this framing comes from the YieldFabric thesis, "The Alignment Economy and Human Quantum Diversity." The thesis argues that real economies are not resource-allocation machines but coordination technologies for human alignment, and that AI's right role is on the edges between humans — as knowledge substrate and translator — not as a replacement for the humans whose live wanting performs the agreement. This guide is the engineering view of that argument; readers wanting the foundational version should read the thesis (especially Part III for the concrete picture).
Aligned economy ≠ alignment economy
A distinction that drives every design decision in the platform.
An aligned economy is a past-tense snapshot — participants matched to roles, relationships held fixed. The infrastructure that serves this is classical: directories, registries, allocations, fixed contracts. It works when goals are stable, participants are interchangeable, and the future looks like the past.
An alignment economy is alive. It is the emergent process of continuously discovering how participants fit together, driven from inside by the wanting of the participants themselves rather than by any central plan or predetermined configuration. New agreements that didn't exist before are generated through the live encounter of people who interpret the world differently.
YieldFabric is infrastructure for the second. Every primitive on this site is a specific operational role in the living alignment process — none of them are "transaction primitives" in isolation.
The five operational roles
When two humans align on something through an AI-augmented conversational interface, five things happen. They are not strictly sequential — the first two are ambient and continuous, the last three are specific to a particular agreement — but they are structurally distinct, and confusing them is the single most common source of mistakes when building on YF.
╭───────────╮ ╭─────────────╮ ╭────────────╮ ╭──────────────╮ ╭───────────╮
│ REASON │ ──► │ COMMUNICATE │ ──► │ NEGOTIATE │ ──► │ STRUCTURE │ ──► │ EXECUTE │
│ │ │ │ │ │ │ │ │ │
╰───────────╯ ╰─────────────╯ ╰────────────╯ ╰──────────────╯ ╰───────────╯
shared relationship wanting gets the collapse: the realised
knowledge channel reshaped by joint state deal — joint
substrate between humans the order of becomes the prompt
that all (AI on the expression definite joint executed as a
participants edges, humans (non-commutative) prompt unit
draw on at the nodes)
What each stage corresponds to in the thesis's three-property description of a human (knowledge + intelligence + intent):
- Reason is the operational form of knowledge — the shared substrate any party can draw interpretation from.
- Communicate is the channel over which intelligences (the differently-shaped interpretive capacities of each participant) get applied to that knowledge in each other's presence.
- Negotiate is where intent — live wanting — is interactively reshaped by the order of expression. The non-commutative middle layer.
- Structure is where the entangled joint wanting collapses into a specific joint prompt — the deal both parties own.
- Execute is the realisation of that joint prompt as on-chain state.
Knowledge, intelligence, possibilities, and the realised deal all commute: order doesn't matter for them. Wanting does not commute — what I come to want after hearing what you want depends on the order of the conversation. That non-commutativity is why classical resource-allocation systems cannot represent what's happening here, and it's why YF stores the chat history as a first-class object: the trajectory IS part of the substrate.
Stage 1 — Reason
Operational role. Build and maintain the shared knowledge substrate that every party draws from when forming interpretations. Not "deciding what to do" — that comes later. Just making sense of the world.
The thesis frame: an LLM is, structurally, a compressed representation of a huge slice of human-accessible knowledge — a high-dimensional vector space sitting on hardware somewhere, that humans now do much of their economic reasoning through. YF makes that substrate live and persistent, scoped to a working group, populated by ingesting documents and conversations into a typed knowledge graph.
YF primitives.
AI's role here. Substantial and visible. The LLM IS the knowledge layer — explicitly, computably, literally. Pipelines run LLM calls to extract frames. The Weaver runs LLM calls to interpret. But notice: at this stage, AI is doing classical work — translating, summarising, indexing, extracting. It carries knowledge and applies intelligence. It is not yet making any agreement; it is preparing the substrate over which agreements will later be formed.
Pitfall. Treating reasoning artifacts as if they were deal terms. An entity the analyser extracted is not a counterparty; a hypothesis is not a proposal; an RFI is not a counter-offer. Reasoning produces substrate. The substrate enables later stages. Don't skip to action because the LLM said something coherent.
➜ Deep dive: Agents, knowledge & workspaces — Knowledge graphs, Pipelines, RAG.
Stage 2 — Communicate
Operational role. Maintain the channel between the parties. Without an ongoing relationship, no new joint wanting can develop between them. With one, the conversation becomes the place where each party's wanting is exposed to the other's, and reshaped by it, in the specific order the exchange happens.
The thesis frame: each participant has a characteristic shape of intelligence — a specific way of writing prompts over shared knowledge that reflects how they interpret things. When two such participants exchange messages, they're not just transferring information; they're each writing prompts in the presence of the other's prompts, and what each one writes next is shaped by what the other has just written. The chat history is the joint state being built up.
YF primitives.
ChatEvent to the group's broadcaster. Privacy-filtered per recipient — Weaver tokens stream to one user without leaking.AI's role here. Edge translation. When one party's characteristic prompts are foreign to the other (a technical expert briefing a policy person; a credit analyst explaining repo mechanics to a startup founder), AI carries the classical translation burden — the "parallel transport" between interpretive frames the thesis describes. This lowers the per-edge maintenance cost of the relationship, which is what makes denser-and-more-direct collaboration graphs economically viable for the first time.
But the conversation itself — the live exchange of expressed wanting in a specific order — is between the humans. The chat history is theirs. AI provides the substrate and the translations. It does not own the conversation, and it does not produce the agreement.
Pitfall. Conflating communication with agreement. Saying "let's do it" in a chat thread doesn't bind anything. Chat is the relationship; agreement comes later, at a specific structural moment (the Intent confirmation). Avoid downstream systems that act on chat content directly without the consent surface in between.
➜ Deep dive: Agents, knowledge & workspaces — Working groups, Threads.
Stage 3 — Negotiate
Operational role. This is where intent — the live, interactively reshaped wanting that sits between possibility and realisation — does its specific work. The participants propose, counter-propose, refine. Each expression of what one wants reshapes the other's wanting. The shape of the deal converges by being walked through.
The thesis frame: real negotiations are observably path-dependent. If Alice expresses her preference first, Bob's response reshapes hers; if Bob had gone first, the conversation reaches a measurably different equilibrium with the same two people and the same starting knowledge. This is non-commutative. Classical probability cannot represent it. The chat history is the joint state, and the trajectory through it is structurally part of the eventual outcome.
YF primitives.
PipelineDraft describing the action being proposed. Reviewable before it becomes a real Intent.Proposed → Confirmed/Cancelled → Executing → Completed/Failed. Each transition emits an SSE event.AI's role here. AI runs the proposing — it can compose a Draft, articulate trade-offs, model the counterparty's interests, run multi-round debate to refine a proposal. It can do all of this because all of it is classical work: knowledge access, possibility enumeration, intelligence-shaped reformulation.
What AI does not do is carry the live wanting whose collapse is the agreement. The Intent is a proposal. It is not a binding agreement until a human confirms it. The confirmation event is the measurement-like operation the thesis describes — the human is the locus of that operation, and AI cannot perform it because AI doesn't carry the non-commutative wanting to collapse.
This is the platform's safety architecture. Agents do not mutate financial state. Agents propose; humans confirm; the system executes the confirmed proposal. The Intent → Confirm boundary is the structural place where wanting collapses into a definite joint prompt. It is not optional, it is not a courtesy, it is the structural locus where alignment happens.
Pitfall. Skipping straight from chat to settlement. Even when an agent is highly autonomous, every state-changing action passes through Intent → Confirm. If you find yourself wanting an agent to "just do it" — to act without a confirmation surface — you are building the resource-economy infrastructure the alignment economy is designed to replace. The friction of the confirmation is the feature.
➜ Deep dive: Agents, knowledge & workspaces — Drafts → Intents → Execution.
Stage 4 — Structure
Operational role. A confirmed Intent is a description — a definite joint prompt — but not yet an artifact. Structure is the operational role of producing the atomic, enforceable, on-chain objects the joint prompt specifies: obligations that one party owes another, swaps that exchange them, repos that lock them, escrows that hold mutual collateral.
The thesis frame: this is the moment of collapse. The chat history — the entangled joint state, with many possible specific deals alive in superposition, weighted by how the interaction has brought each into wanting-salience — gets sent as a joint prompt for execution. Before this moment, the deal was multi-possibility; after this moment, it is definite. The artifact is the evidence that the collapse has happened.
YF primitives. The work at this stage is owned by the DMS
(Deal Management System) — the domain layer that wraps on-chain
artifacts in a legal-shaped envelope with its own state machine,
plan-hash signing protocol, agreement projection, and
pipeline-compilation flow. The agentic persona that drives plan
composition is the seeded deal_structurer agent.
proposeDeal, signDeal, rejectDeal, counterOfferDeal, cancelDeal, activateDeal, processDealPeriod.plan_hash. Includes typed references ($step.X.Y, $cashflow.X, $period.X), an optional periodic_phase, and AgreementMetadata (recitals, governing law, dispute resolution, boilerplate pack).deal_structurer agentexpected, collateral, repurchase), populated in any combination.AI's role here. AI runs the composition: it reads the confirmed Intent + the relevant KG state + the workflow template and constructs the contract / swap / repo specifications. This is classical work — knowledge plus intelligence applied to a definite prompt.
But the structuring step also includes signature gates, human-task reviews, approval gates — these exist because multi-party agreements often require multiple participants to each ratify the shape of the joint prompt. Each ratification is itself a small measurement event — each human confirming that this is indeed the specific deal they want, of all the possibilities still latent.
Pitfall. Confusing structure with execution. A swap in
PENDING is structured but not yet executed; a composed contract
in draft is described but not yet on-chain. Status is the
discriminator. Don't act on a structured-but-unexecuted artifact
as if the transfer had happened.
➜ Deep dives:
- Deal Management System (DMS) — the machinery: DealPlan, propose → sign → activate lifecycle, agreement projection, pipeline compilation.
- Contracts & Obligations — the atomic obligation primitive a DealPlan compiles to.
- Atomic Swaps — bilateral exchange.
- Collateralisation — repo, contingent contracts, rolls, rehypothecation.
Stage 5 — Execute
Operational role. The realised deal. The joint prompt that the structuring stage materialised gets submitted for execution; the on-chain state ratchets forward; the bitemporal projection records the new state; every party sees it via SSE.
The thesis frame: this is the execution of the joint prompt that the measurement event produced. It is the most classical of the five stages — the substantive non-commutative work is already done. What remains is to actualise the definite outcome reliably, verifiably, and confidentially.
YF primitives.
DealCommitted, IntentCompleted, WorkflowEvent::WorkflowComplete. The participants see their realised deal at the same moment.AI's role here. AI runs the surrounding infrastructure — it prepares the execution payload, surfaces the status to the user, generates the natural-language commentary on what just settled. It does not, however, replace the chain — execution is on-chain because the realised deal must be a definite, immutable record that all parties can verify, and AI cannot be the issuer of that record. The classical guarantees of the chain (atomicity, visibility, non-repudiation) are what makes the deal binding after the measurement event.
Pitfall. Treating execute as the start of the relationship. By the time execute fires, communicate has been built, negotiate has converged, structure has produced the artifact. If any of those are absent, execute either fails (validation rejection, ownership check failure) or produces an orphaned record that no downstream consumer can act on.
➜ Deep dives:
- Payments — the transfer primitive.
- Authentication — JWT lifecycle, signatures, delegation.
- Balances — the result of execution as visible state.
AI on the edges, humans at the nodes
The thesis is precise about AI's structural role. It is worth restating here because the platform's whole shape — particularly the Intent → Confirm boundary — only makes sense if you hold this:
AI appears in the framework in two distinct roles. It is the knowledge substrate on which prompts operate — the LLM itself, holding the shared R^n vector space — and it is the tool that enhances the communication coefficient on the edges between humans. These are not different systems; they are two layers of the same technological stack. Both roles are AI, and both are complementary to — not substitutive for — the humans at the nodes who perform the measurement events.
— Part III, What This Means for AI
What AI does in YF: ingests documents, extracts entities, runs reasoning rounds, proposes drafts, composes obligations, translates between interpretive frames, surfaces summaries, runs RAG queries, maintains memory, runs the workflow engine, prepares execution payloads.
What AI does not do in YF: confirm intents, sign on behalf of a party, originate a binding agreement, perform the measurement event that turns possibility into realised deal. Those are reserved for the humans — not because of policy, but because of structure. AI is classical and cannot carry the non-commutative wanting whose collapse is the agreement. Humans are the only systems present that can.
The Intent → Confirm boundary is the engineering form of this structural fact. Every state-changing action in YF — every payment, every swap, every workflow advancement that has external effects — flows through it. The boundary is not a safety check; it is the locus of alignment.
How the stages share substrate
The five stages are not silos. They share three unifying mechanisms:
Stage 1 Reason ──► writes frames ──► KG ◄── reads frames ◄── Stage 2 Communicate
Stage 2 Communicate ──► writes turns ──► KG ◄── reads turns ◄── Stage 3 Negotiate
Stage 3 Negotiate ──► writes Intent ──► Intent ◄── reads Intent ◄── Stage 4 Structure
Stage 4 Structure ──► writes Contract──► Bitemporal store ◄── reads ──── Stage 5 Execute
Stage 5 Execute ──► writes status ──► SSE event broadcast ───────► UI / agents / audit
- The knowledge graph is the shared memory. Reasoning populates it; conversation references it; negotiation produces Intents that point at frames in it; structuring creates contracts linked back to the frames that justified them.
- The Intent record is the consent boundary — the collapse point. It's what an agent produces and a human confirms. Once confirmed, downstream stages have authority to act.
- The SSE event stream is the realtime backbone. Every stage emits events into the working group's broadcaster, so the UI, other agents, audit consumers can observe the whole alignment process in real time without polling.
End-to-end: a deal flowing through all five stages
A concrete walk-through. An issuer wants to securitise a basket of trade receivables and offer Tranche A to a single investor.
Stage 1 — Reason.
The issuer uploads the receivables register and the proposed securitisation memo into their working group's KG. The ingestion pipeline runs: documents become frames, vocabulary is discovered, relationships are extracted. The issuer's Weaver (private subthread) reads the basket composition and flags the 12% concentration to one obligor as elevated risk. The Weaver's intelligence is shaping the issuer's reading; the substrate is now populated. Knowledge substrate established.
Stage 2 — Communicate.
Issuer opens a DM with the investor. They chat. Each message is not in isolation: the investor's first question reshapes the issuer's framing of the next answer, and vice versa. The chat history accumulates as the joint state. The conversation analyzer runs passively, extracting the investor's emerging preferences — yield, rating, timing. Two characteristic intelligences are now in direct contact over the shared substrate. Joint state begins building.
Stage 3 — Negotiate.
The conversation analyzer's observations + the Weaver's flags +
the receivables KG inform the deal_structurer agent's
composition of a Pipeline Draft: Tranche A, $5M face, 5.0% coupon,
AAA representation, end-of-quarter close. The draft includes a
proposed AgreementMetadata block — recitals composed from the
conversation history, governing law and dispute resolution from
the parties' jurisdictions, the appropriate boilerplate pack
selected from the manifest. The Draft becomes an Intent;
IntentProposed SSE fires; the issuer reviews and clicks Confirm.
Measurement event: the entangled joint state collapses into a
definite joint prompt. The issuer's confirmation is the act both
parties have implicitly built up to throughout the conversation —
the structural locus of agreement.
Stage 4 — Structure (DMS).
The confirmed Intent drives the DMS lifecycle. The deal_structurer
agent finalises the candidate DealPlan — a typed action DAG
with the obligation hierarchy (composed contract with 142 child
obligations, coupon obligations, redemption obligation), cashflow
references, and the AgreementMetadata block. The plan is saved
as a Draft via saveDealDraft; the issuer reviews the rendered
agreement markdown (via dealAgreement); the issuer calls
proposeDeal which validates strictly, locks the plan, computes
the canonical-JSON plan_hash, and emits the proposer's signature.
Deal status: Proposed. The investor receives a notification in
their DM thread; reviews the same rendered agreement; calls
signDeal. Deal status: Accepted. The issuer calls
activateDeal — the DMS's pipeline_compile turns the plan
into a WorkflowDefinition and pipeline_submission POSTs it to
agents-api. Deal status: Active; the workflow begins. Multiple
small measurement events along the way — each signature ratifies a
specific aspect of the joint prompt.
Stage 5 — Execute.
The compiled workflow's one-shot phase fires. An automated step
submits createSwap to GraphQL gateway: investor's $5M cash
exchanged atomically for the obligations bundle, with the bundle
becoming a contingent contract held by the investor. MQ pipeline
runs: validation, on-chain execution, the consumer processor writes
the bitemporal Swap row, creates Cont_TrA for the investor.
pipeline_status_mirror consumes the workflow events and writes
them as deal_events on the deal — every step's start, completion,
and any errors land in the deal's audit log. DealCommitted SSE
fires in both workspaces. Deal status will move to Completed once
the periodic phase (coupon payments) finishes, or stay Active
through the deal's life if periodic processing is ongoing. The
joint prompt has executed. The deal is realised state, the deal
audit log is single-source-of-truth, and the agreement markdown
that both parties signed is permanently linked to a plan_hash that
matches what's on-chain.
Five operational roles. One continuous alignment process. The realised deal is on-chain and immutable. The KG that started this journey is still in the issuer's workspace — every claim in the tranche links back to a frame in the original ingestion. The audit trail is end-to-end, and the relationship between issuer and investor — the channel built up in stage 2 — remains live, ready for the next deal.
Don't conflate the stages
Five common confusions. Each one is a category of error:
PENDING swap is treated as settledPENDING swap is real but not active. Status determines what's happened.If you're unsure whether something is reasoning or negotiating, ask: is this fact-gathering, or is this an action a human must confirm before it happens? The second is negotiation. The first is reasoning. Same model, different role.
What this means for what you build
The thesis closes with a personal note that applies equally to applications built on YF:
The question reframes itself. It stops being "will AI replace me?" and becomes: how do you want to align with others, and how can AI — knowledge substrate, classical channel, translator of interpretive frames — help you do it better?
— Part III, What This Means for You
When you build on YF, you are not building "an AI app that does transactions". You are building infrastructure for humans to align on things they could not have pre-computed alone. The AI in your application carries knowledge, runs intelligence, translates between participants whose interpretive frames don't match. The humans carry the wanting whose interactive reshaping makes the agreement possible. The agreement collapses through your application's Intent surface. The realised deal settles on-chain.
Build accordingly. The Intent surface is the most important UI element in your application. The chat history is a first-class state object, not a log. The agents are translators, not deciders. The signature is a measurement event, not a UX detail.
Where to go next, by stage
See also
- The YieldFabric thesis — the foundational argument this platform implements. Part III is the picture-version: two humans, one conversation, one collapse, with every formal object having a direct visible counterpart on the screen.
- Building with YieldFabric — pragmatic HTTP-level reference complementing this conceptual one.
- Cross-service walkthrough — the same end-to-end story as code.
One platform. Five operational roles. Humans at the nodes, AI on the edges. The alignment economy as infrastructure.