worldvm 0.0.0-stage → 0.1.0

package/dist/handle/world.d.ts

@@ -0,0 +1,190 @@
+import * as K from "../_internal/reconciler/index.js";
+import type { SourceFile } from "../_internal/forma/world/index.js";
+import { type ExplainedRequirement } from "../explain.js";
+import { type Store } from "./store.js";
+import type { Draft, Proposal, Request, Result, Verb, Fact, Missing } from "../_internal/protocol/index.js";
+export type Scalar = K.Scalar;
+export type Status = K.Status;
+/** A trusted identity supplied by the embedding application. A bare string is a human. */
+export type Actor = string | {
+    readonly id: string;
+    readonly kind?: "human" | "agent" | "service" | "connector";
+    readonly groups?: readonly string[];
+};
+export interface RequirementStatus {
+    readonly name: string;
+    readonly label: string;
+    readonly status: Status;
+    readonly due: string | null;
+    /** Why nothing can currently advance this requirement, when that is the case. */
+    readonly blocked: string | null;
+}
+export interface InstanceStatus {
+    readonly instance: string;
+    readonly component: string;
+    readonly digest: string;
+    readonly outputs: Readonly<Record<string, Status>>;
+    readonly requirements: readonly RequirementStatus[];
+}
+export interface SubjectStatus {
+    readonly subject: string;
+    readonly at: string;
+    readonly release: string;
+    readonly revision: number;
+    /** The next instant at which this status can change without a new record. */
+    readonly wakeAt: string | null;
+    readonly wakeReason: string;
+    readonly machines: readonly {
+        readonly instance: string;
+        readonly machine: string;
+        readonly state: string | null;
+        readonly since: string | null;
+    }[];
+    readonly instances: readonly InstanceStatus[];
+}
+export interface WorkItem {
+    /** Stable identity derived from the work's inputs; the same work always has the same id. */
+    readonly id: string;
+    readonly instance: string;
+    /** Pass this to `perform`. */
+    readonly operation: string;
+    readonly label: string;
+    readonly kind: "interaction" | "connector" | "decision" | "proposal";
+    readonly proposal?: string;
+    readonly state: "eligible" | "waiting" | "dispatched" | "held";
+    readonly advances: readonly string[];
+    readonly assignee: {
+        readonly id: string | null;
+        readonly kind: "entity" | "group" | "connector";
+    };
+    /** What the action still waits for, when it is not eligible. */
+    readonly missing: readonly Missing[];
+    readonly fields: readonly {
+        readonly field: string;
+        readonly mode: "ask" | "confirm" | "read-only";
+        readonly value: Scalar | null;
+    }[];
+}
+export interface Operation {
+    readonly instance: string;
+    readonly name: string;
+    readonly kind: "action" | "decision";
+    readonly state: K.PublicOperation["state"];
+}
+export interface Change {
+    readonly subject: string;
+    readonly revision: number;
+    readonly at: string;
+    readonly transitions: readonly {
+        readonly instance: string;
+        readonly kind: "requirement" | "output";
+        readonly name: string;
+        readonly from: Status | null;
+        readonly to: Status | null;
+    }[];
+    readonly opened: readonly WorkItem[];
+    readonly closed: readonly WorkItem[];
+}
+export interface Outcome {
+    readonly accepted: boolean;
+    /** Why the command was refused. Empty when accepted. */
+    readonly codes: readonly string[];
+    readonly status: SubjectStatus;
+    readonly change: Change;
+}
+export interface WriteOptions {
+    readonly by: Actor;
+    /** Command identity. Repeating an id with the same content returns the first outcome. */
+    readonly id?: string;
+}
+export interface PerformOptions extends WriteOptions {
+    readonly values?: Readonly<Record<string, Scalar>>;
+    /** Needed only when several of the subject's instances offer the same operation. */
+    readonly instance?: string;
+    readonly signature?: K.IR.SignatureInput;
+    /** Record a draft without attesting it. The only form an agent may submit. */
+    readonly unsigned?: boolean;
+    readonly amend?: K.IR.AmendmentInput;
+    readonly reason?: Scalar | null;
+    readonly revoke?: string;
+}
+export interface Subject {
+    readonly type: string;
+    readonly id: string;
+    readonly propose: (draft: Draft, rationale: string, options: WriteOptions) => Promise<Outcome>;
+    readonly proposals: () => readonly Proposal[];
+    readonly acceptProposal: (proposal: string, options: WriteOptions & {
+        readonly signature?: K.IR.SignatureInput;
+    }) => Promise<Outcome>;
+    readonly rejectProposal: (proposal: string, reason: string, options: WriteOptions) => Promise<Outcome>;
+    /** Record facts about this subject. A null value retracts the attribute. */
+    readonly assert: (values: Readonly<Record<string, Scalar | null>>, options: WriteOptions & {
+        readonly kind?: string;
+    }) => Promise<Outcome>;
+    /** Do a piece of work: submit evidence through an action, or make a decision. */
+    readonly perform: (operation: string, options: PerformOptions) => Promise<Outcome>;
+    /** Record an outside system's observation on a declared machine. */
+    readonly signal: (machine: string, state: string, options: WriteOptions & {
+        readonly instance?: string;
+    }) => Promise<Outcome>;
+    readonly facts: (at?: string) => readonly Fact[];
+    readonly status: (at?: string) => SubjectStatus;
+    readonly work: (at?: string) => readonly WorkItem[];
+    readonly operations: (at?: string) => readonly Operation[];
+    /** Each requirement's rule, citations, reasons, due computation and proof. */
+    readonly explain: (requirement?: string, at?: string) => readonly ExplainedRequirement[];
+}
+export interface World {
+    /** The same schema-checked verbs served by HTTP and MCP. Identity is supplied by the host. */
+    readonly canRead: (actor: Exclude<Actor, string>, type: string, subject: string) => boolean;
+    readonly request: <V extends Verb>(verb: V, input: Request<V>, by: Actor) => Promise<Result<V>>;
+    readonly proposals: () => readonly Proposal[];
+    readonly account: string;
+    readonly release: string;
+    readonly revision: () => number;
+    readonly now: () => string;
+    /** Entity type names this account declares, for `subject(type, id)`. */
+    readonly types: readonly string[];
+    readonly subject: (type: string, id: string) => Subject;
+    /** Ids of every recorded entity of a type. */
+    readonly subjects: (type: string) => readonly string[];
+    /**
+     * Re-evaluate every subject at the current instant and report what time alone changed
+     * (a deadline passed, evidence expired). Call it from a timer; `nextWake` says when.
+     */
+    readonly tick: () => Promise<readonly Change[]>;
+    /** The earliest `wakeAt` across all recorded subjects, or null. */
+    readonly nextWake: () => string | null;
+    /** Called after each committed change. Returns an unsubscribe function. */
+    readonly subscribe: (listener: (change: Change) => void) => () => void;
+    /** The raw append-only records, for export and audit. */
+    readonly records: () => K.World;
+    readonly close: () => Promise<void>;
+}
+export declare class WorldError extends Error {
+    readonly code: string;
+    readonly details: readonly unknown[];
+    constructor(code: string, message: string, details?: readonly unknown[]);
+}
+export interface HostOptions {
+    /** Trusted host authority for protocol subject reads. Defaults to trusted-host access. */
+    readonly canRead?: (request: {
+        readonly actor: Exclude<Actor, string>;
+        readonly type: string;
+        readonly subject: string;
+    }) => boolean;
+    readonly ir: K.IR.WorldIR;
+    /** Source text, when available, so `explain` can quote the rule's prose. */
+    readonly files?: readonly SourceFile[];
+    /** Required when the world declares more than one account. */
+    readonly account?: string;
+    readonly store?: Store;
+    /** Returns the current instant as an ISO date or UTC instant. Defaults to the system clock. */
+    readonly clock?: () => string;
+    /**
+     * Allow opening a store last written under a different release. Statuses are recomputed
+     * under the new rules; nothing is migrated. Without this, a release change is refused.
+     */
+    readonly activate?: boolean;
+}
+export declare const host: (options: HostOptions) => Promise<World>;