@ifsoul/core 0.3.0 → 0.5.0

package/dist/packages/runtime/src/group-scheduler.d.ts

@@ -0,0 +1,165 @@
+import type { BehaviorOperatorPolicy, BehaviorPermissions, BehaviorGoal } from "./behavior-types.js";
+import type { AddressedEvent, ParticipantStore, SessionAccess } from "./participants.js";
+export interface PlanningActor {
+    participantId: string;
+    roleId: string;
+    capabilities: string[];
+}
+export interface PlanningIntent {
+    intentId: string;
+    roleIds: string[];
+    requiredCapabilities: string[];
+}
+export interface GroupPlanningSpec {
+    sessionId: string;
+    sessionRevision: number;
+    groupId?: string;
+    actors: PlanningActor[];
+    intents: PlanningIntent[];
+    objective: string;
+    channelId: string;
+    sharedEventIds: string[];
+    goalId?: string;
+}
+export interface GroupAssignment {
+    assignmentId: string;
+    actorId: string;
+    intentId: string;
+    dependsOn: string[];
+}
+/** Proposal only. No speech, mechanics or successful effects may be returned here. */
+export interface GroupPlan {
+    objective: string;
+    assignments: GroupAssignment[];
+}
+export interface PlanningClock {
+    wallTimeMs: number;
+    worldTicks: Record<string, number>;
+}
+export interface PlanSchedule {
+    scheduleId: string;
+    revision: number;
+    state: "running" | "paused" | "cancelled";
+    spec: GroupPlanningSpec;
+    clock: "wall" | "world";
+    interval: number;
+    nextDue: number;
+    maxRuns: number;
+}
+export type PlanningTrigger = {
+    kind: "due";
+} | {
+    kind: "manual";
+    triggerId: string;
+} | {
+    kind: "event";
+    eventId: string;
+};
+export interface PlanningClaim {
+    claimId: string;
+    fence: number;
+    behaviorRevision?: number;
+    workerId: string;
+    scheduleId: string;
+    scheduleRevision: number;
+    sessionRevision: number;
+    leaseUntil: number;
+    triggerKey: string;
+    actorIds: string[];
+    groupKey: string;
+    status: "active" | "proposed" | "unknown" | "resolved" | "failed" | "superseded";
+    plan?: GroupPlan;
+    adoptedIds?: string[];
+}
+export interface PlanningInput {
+    claim: PlanningClaim;
+    spec: GroupPlanningSpec;
+    sharedEvents: AddressedEvent[];
+    behavior?: {
+        configRevision: number;
+        policy: BehaviorPermissions;
+        goals: BehaviorGoal[];
+    };
+}
+export interface PlanHostReport {
+    reportId: string;
+    claimId: string;
+    status: "adopted" | "rejected" | "completed" | "failed" | "unknown";
+    assignmentIds: string[];
+    summary: string;
+}
+export interface PlanningState {
+    format: "ifsoul-group-scheduler/0.4.0";
+    schedules: PlanSchedule[];
+    claims: PlanningClaim[];
+    reports: PlanHostReport[];
+    cursors: {
+        scheduleId: string;
+        lastClock?: number;
+        lastStarted?: number;
+        runs: number;
+        triggerKeys: string[];
+    }[];
+    lastWallTime: number;
+    calls: number;
+    npcCalls: Record<string, number>;
+    groupCalls: Record<string, number>;
+}
+export interface PlanningBudgets {
+    principalCalls: number;
+    npcCalls: number;
+    groupCalls: number;
+    concurrentPlans: number;
+    schedules: number;
+    claims: number;
+    reports: number;
+    runsPerSchedule: number;
+    actorsPerPlan: number;
+    assignmentsPerPlan: number;
+    assignmentsPerActor: number;
+    sharedEvents: number;
+    contextBytes: number;
+}
+export declare const DEFAULT_PLANNING_LIMITS: Readonly<PlanningBudgets>;
+export declare function resolvePlanningLimits(requested?: Partial<PlanningBudgets>, ceilings?: Partial<PlanningBudgets>): import("../../protocol/src/resource-policy.js").BudgetReport<{
+    principalCalls: number;
+    npcCalls: number;
+    groupCalls: number;
+    concurrentPlans: number;
+    schedules: number;
+    claims: number;
+    reports: number;
+    runsPerSchedule: number;
+    actorsPerPlan: number;
+    assignmentsPerPlan: number;
+    assignmentsPerActor: number;
+    sharedEvents: number;
+    contextBytes: number;
+}>;
+/** Reject the whole proposal. One invalid assignment never grants another action. */
+export declare function validGroupPlan(value: unknown, spec: GroupPlanningSpec, limits?: PlanningBudgets): value is GroupPlan;
+export declare function createGroupSchedulerRuntime(store: ParticipantStore, requestedBudgets?: Partial<PlanningBudgets>, ceilings?: Partial<PlanningBudgets>, behaviorOperator?: BehaviorOperatorPolicy): {
+    configure(access: SessionAccess, expectedRevision: number, config: PlanSchedule): PlanSchedule;
+    control(access: SessionAccess, scheduleId: string, expectedRevision: number, action: "pause" | "resume" | "cancel"): PlanSchedule;
+    list(access: SessionAccess): PlanSchedule[];
+    claim(access: SessionAccess, scheduleId: string, trigger: PlanningTrigger, clock: PlanningClock, workerId: string, leaseMs: number, hostAvailable: boolean): PlanningInput | {
+        status: "not-due" | "paused" | "host-unavailable" | "busy" | "budget" | "replay" | "unknown" | "policy-denied";
+    };
+    complete(access: SessionAccess, ticket: PlanningClaim, output: unknown, clock: PlanningClock): PlanningClaim;
+    fail(access: SessionAccess, ticket: PlanningClaim, uncertain: boolean): PlanningClaim;
+    report(access: SessionAccess, report: PlanHostReport): PlanningClaim;
+    reconcile(access: SessionAccess, claimId: string): PlanningClaim;
+    inspect(access: SessionAccess, scheduleId: string): {
+        config: PlanSchedule;
+        cursor: {
+            scheduleId: string;
+            lastClock?: number;
+            lastStarted?: number;
+            runs: number;
+            triggerKeys: string[];
+        };
+        claims: PlanningClaim[];
+        reports: PlanHostReport[];
+        calls: number;
+    };
+};