@world-engines/tmw 0.1.0-alpha.0

package/dist/runtime.d.ts

@@ -0,0 +1,238 @@
+import { TMW_RUNTIME_GENERATION } from "./runtime-contract.js";
+import type { TmwCapabilityRegistryV3 } from "./capability-registry.js";
+import type { CompiledPlanV3 } from "./compiled-plan.js";
+import { type TmwValueContextV1, type TmwValueGraphV1 } from "./value-graph.js";
+import { type CommittedEventEnvelope, type EventFabricAppendReceipt, type EventFabricSnapshot } from "./event-fabric.js";
+import { type EffectFlowInput, type EffectPlan } from "./effect-flow.js";
+import { type ConditionEvaluationResult, type ConditionGraph, type EvaluationSnapshot } from "./condition-graph.js";
+import type { RuntimeSavPayloadV3 } from "./runtime-sav.js";
+import { type TmwActivationAtomicPort, type TmwActivationCandidateV3, type TmwActivationReceiptV3 } from "./activation.js";
+import type { DurableIntentV3 } from "./durable-intent.js";
+import type { TmwJsonValue } from "./runtime-trace.js";
+import type { TmwConditionExpressionV3, TmwSemanticConditionExpressionV3 } from "./trigger-document-v3.js";
+import { type EventEffectiveTime } from "./time-domains.js";
+import { type TemporalRewriteDraftV3, type TemporalRewriteInterval } from "./temporal-rewrite.js";
+import { type TmwCommittedWriterNoteConsumptionV1, type TmwPendingSceneClockCrossingV1 } from "./scene-state.js";
+export interface TmwRuntimeBindingV3 {
+    readonly epoch: number;
+    readonly runtimeGeneration: typeof TMW_RUNTIME_GENERATION;
+    readonly runtimeContractHash: string;
+    readonly artifactDigest: string;
+    readonly sourceRevision: string;
+    readonly timelineRevision: string;
+    readonly leaseId: string;
+}
+export interface TmwRuntimeActivationResult {
+    readonly condition: ConditionEvaluationResult;
+    readonly effectPlan: EffectPlan;
+}
+export interface TmwRuntimeSemanticPredicateRequest {
+    readonly predicateKey: string;
+    readonly condition: TmwSemanticConditionExpressionV3;
+    readonly evidenceIdentity: Readonly<{
+        readonly eventId: string;
+        readonly eventPayloadHash: string;
+        readonly sourceOperationId: string;
+    }>;
+}
+export interface TmwRuntimeSemanticPredicateVerdict {
+    readonly predicateKey: string;
+    readonly sourceOperationId: string;
+    readonly evidenceSetDigest: string;
+    readonly truth: "true" | "false" | "unknown";
+    readonly confidenceMillionths: number;
+}
+export interface TmwRuntimeSemanticJudgeReceipt {
+    /** Revision 2 receipts. Legacy predicateValues are accepted structurally but never trusted. */
+    readonly verdicts?: ReadonlyArray<TmwRuntimeSemanticPredicateVerdict>;
+    readonly predicateValues?: Readonly<Record<string, "true" | "false" | "unknown">>;
+    readonly budgetReceiptDigest: string;
+    readonly evidenceSetDigest: string;
+    readonly providerReceiptDigest: string;
+    readonly verdictDigest: string;
+}
+export interface TmwRuntimeSemanticJudgePort {
+    judge(input: Readonly<{
+        event: CommittedEventEnvelope;
+        turnId: string;
+        operationId: string;
+        intentId: string;
+        idempotencyKey: string;
+        predicates: ReadonlyArray<TmwRuntimeSemanticPredicateRequest>;
+        /** Compatibility projection for legacy callers; it does not carry enough evidence to be trusted. */
+        predicateKeys: ReadonlyArray<string>;
+    }>): Promise<TmwRuntimeSemanticJudgeReceipt>;
+}
+export interface TmwRuntimeEffectCommitReceipt {
+    readonly preActivationTerminalDigest: string;
+    readonly worldMutationRecoveryOperation: TmwJsonValue | null;
+}
+export interface TmwPreparedWorldMutationBinding {
+    readonly bindingId: string;
+    readonly operationId: string;
+    readonly turnId: string;
+}
+export interface TmwRuntimeEffectCommitPort {
+    prepareWorldMutation(input: Readonly<{
+        epoch: number;
+        runtimeContractHash: string;
+        artifactDigest: string;
+        event: CommittedEventEnvelope;
+        turnId: string;
+        operationId: string;
+        worldEffectNodeIds: ReadonlyArray<string>;
+    }>): Promise<TmwPreparedWorldMutationBinding>;
+    stage(input: Readonly<{
+        event: CommittedEventEnvelope;
+        turnId: string;
+        operationId: string;
+        preparedWorldMutation: TmwPreparedWorldMutationBinding | null;
+        plans: ReadonlyArray<EffectPlan>;
+        durableIntents: ReadonlyArray<DurableIntentV3>;
+    }>): Promise<TmwRuntimeEffectCommitReceipt>;
+    finalizeWorldMutation(input: Readonly<{
+        operationId: string;
+        preparedWorldMutation: TmwPreparedWorldMutationBinding | null;
+    }>): Promise<void>;
+    rollbackWorldMutation(input: Readonly<{
+        operationId: string;
+        preparedWorldMutation: TmwPreparedWorldMutationBinding | null;
+        reason: "activation_conflict" | "activation_failed";
+    }>): Promise<void>;
+}
+/** 已由 Runtime 验证、可与 activation 同一事务消费的作者到 View 下行投影。 */
+export interface TmwVerifiedAuthorViewEvent {
+    readonly eventId: string;
+    readonly eventType: string;
+    readonly viewVisiblePayload: Readonly<Record<string, null | boolean | number | string>>;
+}
+/**
+ * 可选的 activation outbox 暂存 seam。Runtime 只在 verified projection 后暂存；
+ * 真正持久化必须由同一个 activation.commitAtomic 事务消费。
+ */
+export interface TmwVerifiedAuthorViewOutboxPort {
+    stage(input: Readonly<{
+        operationId: string;
+        binding: Readonly<{
+            epoch: number;
+            artifactDigest: string;
+            sourceRevision: string;
+            timelineRevision: string;
+            saveId: string;
+            worldlineId: string;
+        }>;
+        events: ReadonlyArray<TmwVerifiedAuthorViewEvent>;
+    }>): Promise<void>;
+    rollback(input: Readonly<{
+        operationId: string;
+    }>): Promise<void>;
+}
+export interface TmwRuntimeExecutionPorts {
+    readonly semanticJudge: TmwRuntimeSemanticJudgePort;
+    readonly effectCommit: TmwRuntimeEffectCommitPort;
+    readonly activation: TmwActivationAtomicPort;
+    readonly verifiedAuthorViewOutbox?: TmwVerifiedAuthorViewOutboxPort;
+}
+export interface TmwRuntimeTemporalRewriteDraftPort {
+    generate(input: Readonly<{
+        epoch: number;
+        runtimeGeneration: typeof TMW_RUNTIME_GENERATION;
+        runtimeContractHash: string;
+        artifactDigest: string;
+        scenarioId: string;
+        sourceRevision: string;
+        timelineRevision: string;
+        eventLedgerDigest: string;
+        interval: TemporalRewriteInterval;
+        turnId: string;
+        operationId: string;
+        idempotencyKey: string;
+        boundedContext: TmwJsonValue;
+    }>): Promise<TemporalRewriteDraftV3>;
+}
+export interface TmwRuntimeTemporalRewritePorts {
+    readonly draft: TmwRuntimeTemporalRewriteDraftPort;
+    readonly semanticJudge: TmwRuntimeSemanticJudgePort;
+    readonly effectCommit: TmwRuntimeEffectCommitPort;
+    readonly activation: TmwActivationAtomicPort;
+}
+export interface TmwCommittedEventExecutionReceipt {
+    readonly eventReceipt: EventFabricAppendReceipt;
+    readonly activation: TmwActivationReceiptV3;
+    readonly candidate: TmwActivationCandidateV3;
+    /** 仅在本次成功提交消费到 Runtime3 生成的 author projection 时返回。 */
+    readonly authorViewEvents: ReadonlyArray<TmwVerifiedAuthorViewEvent>;
+}
+export interface TmwTemporalRewriteExecutionReceipt {
+    readonly draft: TemporalRewriteDraftV3;
+    readonly activation: TmwActivationReceiptV3;
+    readonly candidate: TmwActivationCandidateV3;
+}
+export interface TmwSuccessfulWriterTurnCommitV1 {
+    readonly operationId: string;
+    readonly turnId: string;
+    readonly worldlineId: string;
+    readonly logicalSeq: number;
+    readonly worldTime: number | null;
+    readonly writerReceiptDigest: string;
+    readonly noteConsumption: Omit<TmwCommittedWriterNoteConsumptionV1, "writerReceiptDigest"> | null;
+    readonly pendingClockCrossings: ReadonlyArray<TmwPendingSceneClockCrossingV1>;
+}
+export interface TmwSuccessfulWriterTurnCommitReceiptV1 {
+    readonly status: "committed" | "already_committed";
+    readonly activation: TmwActivationReceiptV3;
+    /** null only for an idempotent replay whose candidate was committed by an earlier host call. */
+    readonly candidate: TmwActivationCandidateV3 | null;
+}
+export interface TmwRuntimeHostV3 {
+    readonly binding: TmwRuntimeBindingV3;
+    readonly compiledPlan: CompiledPlanV3;
+    restore(payload: RuntimeSavPayloadV3): void;
+    restoredSav(): RuntimeSavPayloadV3 | null;
+    materializeSav(input: Readonly<{
+        turnId: string;
+        preActivationTerminalDigest: string;
+    }>): RuntimeSavPayloadV3;
+    viewEventCommitContext(eventType: string, observation: Readonly<{
+        coordinates: CommittedEventEnvelope["coordinates"];
+        crossingDirection: CommittedEventEnvelope["crossingDirection"];
+    }>): Readonly<{
+        timelineRevision: string;
+        hardFact: boolean;
+        effectiveTime: EventEffectiveTime;
+        coordinates: CommittedEventEnvelope["coordinates"];
+        crossingDirection: CommittedEventEnvelope["crossingDirection"];
+    }>;
+    ingestCommittedEvent(event: CommittedEventEnvelope): Promise<EventFabricAppendReceipt>;
+    executeCommittedEvent(event: CommittedEventEnvelope, ports: TmwRuntimeExecutionPorts): Promise<TmwCommittedEventExecutionReceipt>;
+    commitSuccessfulWriterTurn(input: TmwSuccessfulWriterTurnCommitV1, activation: TmwActivationAtomicPort): Promise<TmwSuccessfulWriterTurnCommitReceiptV1>;
+    rewriteTimeline(input: Readonly<{
+        scenarioId: string;
+        targetWorldTime: number;
+        turnId: string;
+        operationId: string;
+        deadlineEpochMs: number;
+    }>, ports: TmwRuntimeTemporalRewritePorts): Promise<TmwTemporalRewriteExecutionReceipt>;
+    evaluate(input: Readonly<{
+        graph: ConditionGraph;
+        snapshot: EvaluationSnapshot;
+        effectFlow: Omit<EffectFlowInput, "conditionTruth">;
+    }>): TmwRuntimeActivationResult;
+    snapshot(): EventFabricSnapshot;
+    dispose(): void;
+}
+export interface TmwConditionExpressionSnapshotV3 {
+    readonly graph: ConditionGraph;
+    readonly values: Readonly<Record<string, "true" | "false" | "unknown">>;
+    readonly semanticPredicates: ReadonlyArray<Readonly<{
+        predicateKey: string;
+        condition: TmwSemanticConditionExpressionV3;
+    }>>;
+}
+export declare function buildTmwConditionExpressionSnapshotV3(expression: TmwConditionExpressionV3, eventPayload: Readonly<Record<string, TmwJsonValue>>, prefix: string, positiveSemanticLatches?: ReadonlySet<string>, valueContext?: TmwValueContextV1, valueGraph?: TmwValueGraphV1): TmwConditionExpressionSnapshotV3;
+export declare function resolveTmwSemanticPredicateValues(predicates: ReadonlyArray<TmwRuntimeSemanticPredicateRequest>, receipt: TmwRuntimeSemanticJudgeReceipt): Readonly<Record<string, "true" | "false" | "unknown">>;
+export declare function createTmwRuntimeHost(input: Readonly<{
+    binding: TmwRuntimeBindingV3;
+    compiledPlan: CompiledPlanV3;
+    capabilityRegistry: TmwCapabilityRegistryV3;
+}>): TmwRuntimeHostV3;