@manifesto-ai/governance 0.1.1 → 3.1.1

package/README.md

@@ -1,52 +1,73 @@
 # @manifesto-ai/governance
 
-> Split-native governance protocol for legitimacy, authority, and proposal lifecycle.
+> Decorator runtime for legitimacy, approval, and governed execution.
 
-`@manifesto-ai/governance` is the package to use when you need to reason about proposal legitimacy directly. It owns the governance lifecycle and composes with `@manifesto-ai/lineage` when you need branch-aware sealing.
+`@manifesto-ai/governance` is the package that turns a composable manifesto into a governed world. Its canonical public entry is `withGovernance(manifesto, config)`.
 
-> **Current Contract Note:** The current public package contract is documented in [docs/governance-SPEC-2.0.0v.md](docs/governance-SPEC-2.0.0v.md). The v1.0.0 governance spec remains available as the historical split-era baseline.
+> **Current Contract Note:** The truthful current package contract is [docs/governance-SPEC-v3.0.0-draft.md](docs/governance-SPEC-v3.0.0-draft.md). The v2.0.0 governance spec remains as the historical service-first baseline.
 
-## What This Package Owns
+## Canonical Runtime Path
+
+```ts
+import { createManifesto } from "@manifesto-ai/sdk";
+import { createInMemoryLineageStore, withLineage } from "@manifesto-ai/lineage";
+import { withGovernance } from "@manifesto-ai/governance";
+
+const governed = withGovernance(
+  withLineage(createManifesto<CounterDomain>(schema, effects), {
+    store: createInMemoryLineageStore(),
+  }),
+  {
+    bindings,
+    execution: {
+      projectionId: "counter",
+      deriveActor(intent) {
+        return { actorId: "agent:demo", kind: "agent" };
+      },
+      deriveSource(intent) {
+        return { kind: "agent", eventId: intent.intentId };
+      },
+    },
+  },
+).activate();
 
-- proposal lifecycle and status changes
-- actor and authority binding
-- execution-key policy and context
-- governance events and event dispatch
-- in-memory governance storage
-- intent-instance helpers
-
-## When to Use It
-
-Use `@manifesto-ai/governance` directly when you want:
-
-- custom governance evaluation or policy logic
-- isolated tests for proposal lifecycle behavior
-- explicit control over authority and event dispatch
-- a lower-level building block for `@manifesto-ai/world`
-
-## Quick Start
-
-```typescript
-import {
-  createGovernanceEventDispatcher,
-  createGovernanceService,
-  createInMemoryGovernanceStore,
-} from "@manifesto-ai/governance";
-import { createLineageService, createInMemoryLineageStore } from "@manifesto-ai/lineage";
-
-const lineageStore = createInMemoryLineageStore();
-const lineage = createLineageService(lineageStore);
-const governanceStore = createInMemoryGovernanceStore();
-const governance = createGovernanceService(governanceStore, {
-  lineageService: lineage,
-});
-const eventDispatcher = createGovernanceEventDispatcher({ service: governance });
+const proposal = await governed.proposeAsync(
+  governed.createIntent(governed.MEL.actions.increment),
+);
 ```
 
+## What This Package Owns
+
+- `withGovernance()` and the activated `GovernanceInstance`
+- proposal lifecycle and authority evaluation
+- pending human/tribunal resolution through `approve()` / `reject()`
+- governance decision records and post-commit governance events
+- low-level governance stores, services, authority handlers, and intent-instance helpers
+
+## What Changes After Governance Activation
+
+- direct `dispatchAsync` and `commitAsync` no longer exist
+- the canonical state-change path becomes `proposeAsync() -> approve()/reject()`
+- lineage must be composed before governance activation
+- visible snapshots publish only after approved execution seals successfully
+
+## Low-Level Surface Still Available
+
+The service-first exports remain public for lower-level tooling and protocol tests:
+
+- `createGovernanceService()`
+- `createGovernanceEventDispatcher()`
+- `createInMemoryGovernanceStore()`
+- `createAuthorityEvaluator()`
+- authority handlers and lifecycle types
+
+Those are no longer the canonical application entry story.
+
 ## Docs
 
 - [Docs Landing](docs/README.md)
 - [Governance Guide](docs/GUIDE.md)
-- [Governance Specification](docs/governance-SPEC-2.0.0v.md)
+- [Governance Specification](docs/governance-SPEC-v3.0.0-draft.md)
+- [Historical v2 Baseline](docs/governance-SPEC-2.0.0v.md)
 - [Historical v1 Baseline](docs/governance-SPEC-1.0.0v.md)
 - [VERSION-INDEX](docs/VERSION-INDEX.md)

package/dist/authority/auto.d.ts

@@ -0,0 +1,6 @@
+import type { ActorAuthorityBinding, AuthorityResponse, Proposal } from "../types.js";
+import type { AuthorityHandler } from "./types.js";
+export declare class AutoApproveHandler implements AuthorityHandler {
+    evaluate(proposal: Proposal, binding: ActorAuthorityBinding): Promise<AuthorityResponse>;
+}
+export declare function createAutoApproveHandler(): AutoApproveHandler;

package/dist/authority/evaluator.d.ts

@@ -0,0 +1,33 @@
+import type { ActorAuthorityBinding, AuthorityKind, AuthorityResponse, IntentScope, Proposal } from "../types.js";
+import type { AuthorityHandler } from "./types.js";
+import { AutoApproveHandler } from "./auto.js";
+import { HITLHandler } from "./hitl.js";
+import { PolicyRulesHandler } from "./policy.js";
+import { TribunalHandler } from "./tribunal.js";
+export declare class AuthorityEvaluator {
+    private readonly handlers;
+    private readonly autoHandler;
+    private readonly policyHandler;
+    private readonly hitlHandler;
+    private readonly tribunalHandler;
+    constructor();
+    evaluate(proposal: Proposal, binding: ActorAuthorityBinding): Promise<AuthorityResponse>;
+    registerHandler(policyMode: string, handler: AuthorityHandler): void;
+    getAutoHandler(): AutoApproveHandler;
+    getPolicyHandler(): PolicyRulesHandler;
+    getHITLHandler(): HITLHandler;
+    getTribunalHandler(): TribunalHandler;
+    getAuthorityKind(policyMode: string): AuthorityKind | null;
+    submitHITLDecision(proposalId: string, decision: "approved" | "rejected", reasoning?: string, approvedScope?: IntentScope | null): void;
+    submitTribunalVote(proposalId: string, voter: {
+        actorId: string;
+        kind: "human" | "agent" | "system";
+        name?: string;
+    }, decision: "approve" | "reject" | "abstain", reasoning?: string): void;
+    hasPendingHITL(): boolean;
+    hasPendingTribunal(): boolean;
+    getPendingHITLIds(): string[];
+    getPendingTribunalIds(): string[];
+    clearAllPending(): void;
+}
+export declare function createAuthorityEvaluator(): AuthorityEvaluator;

package/dist/authority/hitl.d.ts

@@ -0,0 +1,14 @@
+import type { ActorAuthorityBinding, AuthorityResponse, IntentScope, Proposal } from "../types.js";
+import type { AuthorityHandler } from "./types.js";
+export type HITLNotificationCallback = (proposalId: string, proposal: Proposal, binding: ActorAuthorityBinding) => void;
+export declare class HITLHandler implements AuthorityHandler {
+    private readonly pendingDecisions;
+    private readonly notificationCallbacks;
+    onPendingDecision(callback: HITLNotificationCallback): () => void;
+    evaluate(proposal: Proposal, binding: ActorAuthorityBinding): Promise<AuthorityResponse>;
+    submitDecision(proposalId: string, decision: "approved" | "rejected", reasoning?: string, approvedScope?: IntentScope | null): void;
+    isPending(proposalId: string): boolean;
+    getPendingIds(): string[];
+    clearAllPending(): void;
+}
+export declare function createHITLHandler(): HITLHandler;

package/dist/authority/policy.d.ts

@@ -0,0 +1,12 @@
+import type { ActorAuthorityBinding, AuthorityResponse, Proposal } from "../types.js";
+import type { AuthorityHandler } from "./types.js";
+export type CustomConditionEvaluator = (proposal: Proposal, binding: ActorAuthorityBinding) => boolean;
+export declare class PolicyRulesHandler implements AuthorityHandler {
+    private readonly customEvaluators;
+    registerCustomEvaluator(name: string, evaluator: CustomConditionEvaluator): void;
+    evaluate(proposal: Proposal, binding: ActorAuthorityBinding): Promise<AuthorityResponse>;
+    private evaluateCondition;
+    private matchPattern;
+    private applyDecision;
+}
+export declare function createPolicyRulesHandler(): PolicyRulesHandler;

package/dist/authority/tribunal.d.ts

@@ -0,0 +1,16 @@
+import type { ActorAuthorityBinding, ActorRef, AuthorityResponse, Proposal, Vote } from "../types.js";
+import type { AuthorityHandler } from "./types.js";
+export type TribunalNotificationCallback = (proposalId: string, proposal: Proposal, members: readonly ActorRef[]) => void;
+export declare class TribunalHandler implements AuthorityHandler {
+    private readonly pendingTribunals;
+    private notificationCallback?;
+    onPendingTribunal(callback: TribunalNotificationCallback): void;
+    evaluate(proposal: Proposal, binding: ActorAuthorityBinding): Promise<AuthorityResponse>;
+    submitVote(proposalId: string, voter: ActorRef, decision: "approve" | "reject" | "abstain", reasoning?: string): void;
+    isPending(proposalId: string): boolean;
+    getVotes(proposalId: string): Vote[];
+    getPendingIds(): string[];
+    clearAllPending(): void;
+    private checkQuorum;
+}
+export declare function createTribunalHandler(): TribunalHandler;

package/dist/authority/types.d.ts

@@ -0,0 +1,14 @@
+import type { ActorAuthorityBinding, AuthorityResponse, Proposal } from "../types.js";
+export interface AuthorityHandler {
+    evaluate(proposal: Proposal, binding: ActorAuthorityBinding): Promise<AuthorityResponse>;
+}
+export interface HITLDecisionCallback {
+    (proposalId: string, decision: "approved" | "rejected", reasoning?: string): void;
+}
+export interface HITLPendingState {
+    proposalId: string;
+    proposal?: Proposal;
+    resolve: (response: AuthorityResponse) => void;
+    reject: (error: Error) => void;
+    timeoutId?: ReturnType<typeof setTimeout>;
+}

package/dist/event-dispatcher.d.ts

@@ -0,0 +1,7 @@
+import { type GovernanceEventDispatcher, type GovernanceEventSink, type GovernanceService } from "./types.js";
+export interface CreateGovernanceEventDispatcherOptions {
+    readonly service: Pick<GovernanceService, "createExecutionCompletedEvent" | "createExecutionFailedEvent" | "createWorldCreatedEvent" | "createWorldForkedEvent">;
+    readonly sink?: GovernanceEventSink;
+    readonly now?: () => number;
+}
+export declare function createGovernanceEventDispatcher(options: CreateGovernanceEventDispatcherOptions): GovernanceEventDispatcher;