@manifesto-ai/world

World is the governance layer of Manifesto. It manages authority, proposals, decision records, and lineage.

What is World?

World operates above Core and Host, governing who can propose changes, who can approve them, and tracking the complete history of all state transitions. World never imports Host directly; App provides a HostExecutor adapter.

In the Manifesto architecture:

App -> WORLD -> Host -> Core
        |
  Governs legitimacy, authority, lineage
  Tracks WHO proposed WHAT, WHEN, WHY

What World Does

| Responsibility | Description | |----------------|-------------| | Manage actors | Register and track actors (human, agent, system) | | Evaluate authority | Route proposals to appropriate authority handlers | | Track proposals | Full lifecycle from submission to completion | | Maintain lineage | DAG of World ancestry (who came from where) | | Create decision records | Immutable audit trail of authority decisions |

What World Does NOT Do

| NOT Responsible For | Who Is | |--------------------|--------| | Compute state transitions | Core | | Execute effects | Host | | Handle UI/event bindings | App | | Define domain logic | App |

Installation

npm install @manifesto-ai/world @manifesto-ai/core
# or
pnpm add @manifesto-ai/world @manifesto-ai/core

Quick Example

import { createManifestoWorld, createIntentInstance } from "@manifesto-ai/world";

const world = createManifestoWorld({
  schemaHash: "todo-v1",
  executor: appHostExecutor, // App-provided HostExecutor (optional)
});

// Register an actor
const actor = {
  actorId: "user-1",
  kind: "human",
  name: "Alice",
};
world.registerActor(actor, { mode: "auto_approve" });

// Create genesis world
const initialSnapshot = /* Snapshot from Core */;
const genesis = await world.createGenesis(initialSnapshot);

// Build intent instance
const intent = await createIntentInstance({
  body: {
    type: "todo.add",
    input: { title: "Buy milk" },
  },
  schemaHash: world.schemaHash,
  projectionId: "app:ui",
  source: { kind: "ui", eventId: "evt-1" },
  actor,
});

// Submit a proposal
const result = await world.submitProposal(actor.actorId, intent, genesis.worldId);

console.log(result.proposal.status); // -> "completed" | "failed" | "rejected" | "evaluating"
if (result.resultWorld) {
  console.log(result.resultWorld.worldId); // -> "w_abc123..."
}

See GUIDE.md for the full tutorial.

World API

Main Exports

// Factory
function createManifestoWorld(config: ManifestoWorldConfig): ManifestoWorld;

// World class
class ManifestoWorld {
  registerActor(actor: ActorRef): void;
  registerActor(actor: ActorRef, policy: AuthorityPolicy): void;
  updateActorBinding(actorId: string, policy: AuthorityPolicy): void;
  submitProposal(actorId: string, intent: IntentInstance, baseWorld: WorldId, trace?: ProposalTrace): Promise<ProposalResult>;
  processHITLDecision(proposalId: string, decision: "approved" | "rejected", reason?: string, approvedScope?: IntentScope | null): Promise<ProposalResult>;
  getWorld(worldId: WorldId): Promise<World | null>;
  getSnapshot(worldId: WorldId): Promise<Snapshot | null>;
  getProposal(proposalId: string): Promise<Proposal | null>;
  getEvaluatingProposals(): Promise<Proposal[]>;
}

// Key types
type World = { worldId, schemaHash, snapshotHash, createdAt, createdBy };
type Proposal = { proposalId, actor, intent, baseWorld, status, decisionId? };
type DecisionRecord = { decisionId, proposalId, authority, decision, decidedAt };
type ActorRef = { actorId, kind: "human" | "agent" | "system", name?, meta? };

See SPEC.md for complete API reference.

Core Concepts

Authority System

World supports multiple authority types:

| Authority | Description | |-----------|-------------| | auto | Auto-approve all proposals (no deliberation) | | policy | Rule-based decisions (path restrictions, rate limits) | | human | Human-in-the-loop approval required | | tribunal | Multi-agent review process |

// Human-in-the-loop example
const reviewer = { actorId: "human-1", kind: "human" };
world.registerActor(
  { actorId: "agent-1", kind: "agent" },
  { mode: "hitl", delegate: reviewer }
);

Proposal Lifecycle

submitted -> evaluating -> approved -> executing -> completed
                     v                    v
                  rejected              failed

Immutable Worlds

Each successful proposal creates a new World. Worlds are immutable and form a DAG (directed acyclic graph) of lineage.

Relationship with Other Packages

App -> WORLD -> Host

| Relationship | Package | How | |--------------|---------|-----| | Depends on | @manifesto-ai/core | Uses Core types | | Integrates with | @manifesto-ai/host | Via HostExecutor adapter (App-provided) |

When to Use World Directly

Use World directly when:

• Building applications with governance requirements
• Implementing human-in-the-loop approval flows
• Tracking audit trails for compliance
• Building multi-agent systems with authority policies

For simple applications without governance, you can use Host directly.

Documentation

| Document | Purpose | |----------|---------| | GUIDE.md | Step-by-step usage guide | | world-SPEC-v2.0.2.md | Complete specification | | world-FDR-v2.0.2.md | Design rationale | | VERSION-INDEX.md | Version history |

License

MIT