Architecture

PartyVM builds coordination directly on Triplex. Foldworks provides the interface for interacting with that model.

Foldworks interface → PartyVM commands → Triplex transactions
                    ← participant view ← facts + history

Start with facts and responsibility

A party is a boundary around participants, assigned work, and a shared goal. The first implementation has three operations: add a participant, complete an obligation, and hand off an obligation. Each operates on Triplex facts.

Foundation	Responsibility
Triplex	Entity facts, atomic transactions, revision preconditions, command receipts, transaction history
PartyVM core	Party scope, membership, roles, assignment, dependencies, visibility, handoffs, goal readiness
Foldworks + Foldkit	Components, participant selection, commands, loading and failure states
Applications	Domain-specific meaning and integrations; onboarding is the first example

Implemented model

packages/core exports Effect operations and runtime schemas. Entity keys include the party ID, entity kind, and local ID. The same participant ID in two parties does not share facts or authority automatically.

PartyInput {
  id, name, goal,
  participants: [{ id, name, role }],
  obligations: [{ id, title, assigneeId, dependsOn, visibility }]
}

This outline omits TypeScript types for readability; the schemas in the package are authoritative. Roles in this first policy are worker, employer, provider, and coordinator. A party has 1–100 initial participants and 1–100 obligations. Participant IDs and obligation IDs must be unique within their respective sets. Dependencies must exist in the same party and form an acyclic graph.

An obligation keeps the required role of its initial assignee. A handoff may move it to another participant with that role. Only the current assignee can complete it, and only after every prerequisite is complete. The shared goal is ready when all obligations are complete; readiness is derived rather than independently set.

Commands and atomicity

The host supplies an actor ID separately from a command. The core checks membership, visibility, and the operation's permissions before writing.

A command commits its fact changes, party revision, and audit record in one Triplex transaction. The transaction has a precondition on the party root's exact fact set. Concurrent changes cause a conflict rather than silently overwriting one another. The caller can reread state and retry with the same request ID.

Request IDs are scoped to the party. An exact retry returns the original receipt; reuse with a different payload or actor fails. Each audit record captures the actor, acting role, policy version, summary, and command payload. Triplex retains the underlying asserted and retracted facts.

All domain writes must go through PartyVM for this revision protocol to hold. The core is a trusted application library; raw access to the Triplex store bypasses its coordination rules.

Perspective and visibility

readParty(partyId, actorId) returns the member directory, shared goal, visible obligations, permitted actions, and recent visible history.

• Party-visible work is readable by every participant.
• Assignee-visible work is readable by its current assignee and coordinators.
• History about hidden work is filtered using current visibility.
• Goal counts are intentionally party-wide, including private work. They reveal aggregate progress, but not private task titles or transaction details.
• History reads the latest 100 party transactions before filtering. Older visible entries may therefore fall outside the returned window.

Permission hints in the interface are for usability. Command execution repeats the checks in the core.

Agents and authority

The example's coordination agent is a participant with the coordinator role. It can add participants and hand off work; it cannot complete someone else's obligation. The sandbox lets you select this perspective manually. No language model or autonomous agent is connected yet.

A future agent host can use the same readParty and execute operations as the interface, binding the actor ID to its authenticated identity.

Sandbox boundary

The sandbox runs a real Triplex store entirely in memory in each browser tab. Switching participants demonstrates perspectives; it is not authentication. Refreshing discards changes. No party data is uploaded or shared between visitors.

Before shared production use, PartyVM needs a server host, authenticated actor binding, durable storage, and an API that exposes filtered views rather than raw Triplex facts. The current role policy is fixed and versioned in code.

Next extensions

Add these against concrete application needs:

1. A durable server adapter using Triplex storage and authenticated identities.
2. Evidence and approvals, with explicit decisions and supporting facts.
3. External effects with delivery receipts and retry semantics.
4. Application-defined roles and policies, and explicit rules for nested parties.

The current package does not implement those extensions or employment compliance.