@unrulysystems/native-motion-core 0.1.0-alpha.0

package/dist/external-animation-ledger.d.ts

@@ -0,0 +1,416 @@
+import type { MotionGraph } from "./types.js";
+export type PublicControlSlotState = {
+    readonly kind: 'empty';
+} | {
+    readonly kind: 'installed';
+    readonly controlId: number;
+    readonly executionId: number;
+};
+/** Immutable identity-side reference to one dependency in the canonical graph-global batch. */
+export interface TargetBatchDependencyReference {
+    readonly batchId: number;
+    readonly dependencyId: number;
+    readonly valueCompletionSequence: number;
+}
+export type PublicIdentityTargetBatchDependencySource = {
+    readonly kind: 'public-identity';
+    readonly identityId: number;
+    readonly executionId: number;
+};
+export type PrivateControlTargetBatchDependencySource = {
+    readonly kind: 'private-control';
+    readonly controlId: number;
+};
+/** Immutable provenance for one dependency in the canonical graph-global batch. */
+export type TargetBatchDependencySource = PublicIdentityTargetBatchDependencySource | PrivateControlTargetBatchDependencySource;
+interface ExternalAnimationExecutionIdentity {
+    readonly executionId: number;
+    readonly controlId: number;
+    readonly creationSequence: number;
+    readonly directOperationEpoch: number;
+    /** Captured in authored order; the canonical batch record never enters execution state. */
+    readonly capturedTargetBatchDependencies: readonly TargetBatchDependencyReference[];
+}
+export type ExternalAnimationExecutionState = (ExternalAnimationExecutionIdentity & {
+    readonly kind: 'running-unarmed';
+}) | (ExternalAnimationExecutionIdentity & {
+    readonly kind: 'completion-armed-running';
+    readonly completionSequence: number;
+    readonly lifecycleEventSequence: number;
+    readonly cancellationCountAfterArm: number;
+}) | (ExternalAnimationExecutionIdentity & {
+    readonly kind: 'completion-armed-physical-resolved';
+    readonly completionSequence: number;
+    readonly lifecycleEventSequence: number;
+    readonly cancellationCountAfterArm: number;
+}) | (ExternalAnimationExecutionIdentity & {
+    readonly kind: 'completion-dispatching';
+    readonly completionSequence: number;
+    readonly lifecycleEventSequence: number;
+    readonly cancellationCountAfterArm: number;
+}) | (ExternalAnimationExecutionIdentity & {
+    readonly kind: 'awaiting-completion-authoritative-acknowledgement';
+    readonly completionSequence: number;
+    readonly lifecycleEventSequence: number;
+    readonly publicStartPromiseResolved: true;
+}) | (ExternalAnimationExecutionIdentity & {
+    readonly kind: 'awaiting-cancellation-authoritative-acknowledgement';
+    readonly cancellationSequence: number;
+    readonly rawControlPromise: 'permanently-pending';
+    readonly publicControlSlotCleared: true;
+    /** Independent from acknowledgement of every caused identity-outbox event. */
+    readonly authoritativeCancellationAcknowledged: boolean;
+});
+interface TargetBatchDependencyEventIdentity {
+    readonly batchId: number;
+    readonly dependencyId: number;
+    readonly source: TargetBatchDependencySource;
+    readonly valueCompletionSequence: number;
+    readonly eventSequence: number;
+}
+export type TargetBatchDependencyEvent = (TargetBatchDependencyEventIdentity & {
+    readonly kind: 'raw-resolved';
+}) | (TargetBatchDependencyEventIdentity & {
+    readonly kind: 'value-acknowledged';
+}) | (TargetBatchDependencyEventIdentity & {
+    readonly kind: 'permanently-unresolved';
+});
+export type IdentityTargetBatchDependencyEvent = TargetBatchDependencyEvent & {
+    readonly source: PublicIdentityTargetBatchDependencySource;
+};
+export interface IdentityTargetBatchDependencyEventOutboxEntry {
+    readonly event: IdentityTargetBatchDependencyEvent;
+}
+export interface TargetBatchDependencyAcknowledgement extends TargetBatchDependencyReference {
+    readonly valueAcknowledgedEventSequence: number;
+}
+interface TargetBatchDependencyIdentity {
+    readonly dependencyId: number;
+    readonly source: TargetBatchDependencySource;
+    readonly valueCompletionSequence: number;
+}
+export type TargetBatchDependencyState = (TargetBatchDependencyIdentity & {
+    readonly kind: 'waiting-raw';
+    readonly eventAckWatermark: number;
+}) | (TargetBatchDependencyIdentity & {
+    readonly kind: 'waiting-value-acknowledgement';
+    readonly rawResolvedEventSequence: number;
+    readonly eventAckWatermark: number;
+}) | (TargetBatchDependencyIdentity & {
+    readonly kind: 'acknowledged';
+    readonly rawResolvedEventSequence: number;
+    readonly valueAcknowledgedEventSequence: number;
+    readonly eventAckWatermark: number;
+}) | (TargetBatchDependencyIdentity & {
+    readonly kind: 'permanently-unresolved';
+    readonly eventSequence: number;
+    readonly eventAcknowledged: boolean;
+});
+interface TargetBatchActivityIdentity {
+    readonly batchId: number;
+    readonly dependencies: readonly TargetBatchDependencyState[];
+}
+export interface TargetBatchAuthoredCarrier {
+    readonly identityId: number;
+    readonly carrierSequence: number;
+}
+/** One exact carrier whose queued write/commit still owns pending-frame retention. */
+export interface PendingFrameActivityRetention {
+    readonly carrierSequence: number;
+}
+interface SealedTargetBatchActivityIdentity extends TargetBatchActivityIdentity {
+    readonly aggregateReactionSequence: number;
+    readonly authoredCarriers: readonly TargetBatchAuthoredCarrier[];
+}
+export type TargetBatchActivityState = (TargetBatchActivityIdentity & {
+    readonly kind: 'capturing';
+    readonly aggregateReactionSequence: null;
+}) | (TargetBatchActivityIdentity & {
+    readonly kind: 'waiting-dependencies';
+    readonly aggregateReactionSequence: number;
+    readonly authoredCarriers: readonly TargetBatchAuthoredCarrier[];
+}) | (SealedTargetBatchActivityIdentity & {
+    readonly kind: 'sealed-empty';
+    readonly dependencies: readonly [];
+    readonly nextCarrierRetentionIndex: number;
+}) | (SealedTargetBatchActivityIdentity & {
+    readonly kind: 'ready-awaiting-carrier-retention';
+    readonly nextCarrierRetentionIndex: number;
+}) | (SealedTargetBatchActivityIdentity & {
+    readonly kind: 'ready-awaiting-delivery';
+}) | (SealedTargetBatchActivityIdentity & {
+    readonly kind: 'waiting-orchestration';
+}) | (TargetBatchActivityIdentity & {
+    readonly kind: 'permanently-unrunnable';
+    readonly aggregateReactionSequence: number;
+    readonly authoredCarriers: readonly TargetBatchAuthoredCarrier[];
+    readonly everyOtherDependencyTerminal: boolean;
+    readonly unacknowledgedEventCount: number;
+}) | {
+    readonly kind: 'released';
+    readonly batchId: number;
+    readonly terminal: 'delivered' | 'permanently-unrunnable';
+};
+export interface ExternalAnimationIdentityAuthorityState {
+    readonly identityId: number;
+    readonly publicControlSlot: PublicControlSlotState;
+    readonly executions: readonly ExternalAnimationExecutionState[];
+    /** Public-identity events retained until the matching identity authority accepts their ack. */
+    readonly identityTargetBatchDependencyEventOutbox: readonly IdentityTargetBatchDependencyEventOutboxEntry[];
+    readonly identityTargetBatchDependencyEventAcknowledgementWatermark: number;
+    readonly nextIdentityTargetBatchDependencyEventSequence: number;
+    readonly pendingFrameActivities: readonly PendingFrameActivityRetention[];
+    /** Exact identity-local sequences retained as replay tombstones. */
+    readonly releasedPendingFrameActivities: readonly PendingFrameActivityRetention[];
+    /** Highest authoritative execution acknowledgement irreversibly accepted. */
+    readonly authoritativeAcknowledgementWatermark: number;
+    readonly nextExecutionCreationSequence: number;
+}
+/** The one canonical target-batch authority for the entire Motion graph. */
+export interface ExternalAnimationTargetBatchAuthorityState {
+    readonly targetBatchActivities: readonly TargetBatchActivityState[];
+    readonly nextAggregateReactionSequence: number;
+}
+export interface ExternalAnimationLedgerState {
+    readonly identityAuthorities: readonly ExternalAnimationIdentityAuthorityState[];
+    readonly targetBatchAuthority: ExternalAnimationTargetBatchAuthorityState;
+}
+export interface ExternalAnimationIdentityObservation {
+    readonly identityId: number;
+    readonly publicControlSlotExecutionId: number | null;
+    readonly retainedPhysicalExecutionCount: number;
+    readonly externalActiveAnimationCount: number;
+    readonly completionArmedExecutionCount: number;
+    readonly awaitingAuthoritativeAcknowledgementCount: number;
+    readonly pendingFrameActivityCount: number;
+    readonly identityTargetBatchDependencyEventOutboxCount: number;
+    readonly identityTargetBatchDependencyEventAcknowledgementWatermark: number;
+    readonly authoritativeAcknowledgementWatermark: number;
+}
+export interface ExternalAnimationLedgerObservation {
+    readonly identityObservations: readonly ExternalAnimationIdentityObservation[];
+    readonly retainedPhysicalExecutionCount: number;
+    readonly externalActiveAnimationCount: number;
+    readonly completionArmedExecutionCount: number;
+    readonly awaitingAuthoritativeAcknowledgementCount: number;
+    readonly openTargetBatchActivityCount: number;
+    readonly pendingFrameActivityCount: number;
+    readonly identityTargetBatchDependencyEventOutboxCount: number;
+    readonly combinedActiveAnimationCount: number;
+    readonly isSettled: boolean;
+}
+export type ExternalAnimationLedgerEvent = {
+    readonly kind: 'register-external-animation-identity';
+    readonly identityId: number;
+} | {
+    readonly kind: 'retire-external-animation-identity';
+    readonly identityId: number;
+} | {
+    readonly kind: 'install-ordinary-execution';
+    readonly identityId: number;
+    readonly executionId: number;
+    readonly controlId: number;
+    readonly creationSequence: number;
+    readonly directOperationEpoch: number;
+} | {
+    readonly kind: 'replace-public-control-slot';
+    readonly identityId: number;
+    readonly executionId: number;
+    readonly controlId: number;
+} | {
+    readonly kind: 'capture-execution-target-batch-dependency';
+    readonly identityId: number;
+    readonly executionId: number;
+    readonly batchId: number;
+    readonly dependencyId: number;
+    readonly valueCompletionSequence: number;
+} | {
+    readonly kind: 'arm-completion-before-final-change';
+    readonly identityId: number;
+    readonly executionId: number;
+    readonly completionSequence: number;
+    readonly lifecycleEventSequence: number;
+} | {
+    readonly kind: 'cancel-installed-control';
+    readonly identityId: number;
+    readonly cancellationSequence: number;
+} | {
+    readonly kind: 'acknowledge-cancellation';
+    readonly identityId: number;
+    readonly executionId: number;
+    readonly cancellationSequence: number;
+    readonly authoritativeAcknowledgementSequence: number;
+} | {
+    readonly kind: 'resolve-armed-physical-execution';
+    readonly identityId: number;
+    readonly executionId: number;
+    readonly completionSequence: number;
+} | {
+    readonly kind: 'drain-armed-completion';
+    readonly identityId: number;
+    readonly executionId: number;
+    readonly completionSequence: number;
+} | {
+    readonly kind: 'finish-completion-dispatch';
+    readonly identityId: number;
+    readonly executionId: number;
+    readonly completionSequence: number;
+} | {
+    readonly kind: 'acknowledge-completion';
+    readonly identityId: number;
+    readonly executionId: number;
+    readonly completionSequence: number;
+    readonly authoritativeAcknowledgementSequence: number;
+    /** Must match the execution's immutable captured set in authored order. */
+    readonly targetBatchDependencyAcknowledgements: readonly TargetBatchDependencyAcknowledgement[];
+} | {
+    readonly kind: 'open-target-batch-activity';
+    readonly batchId: number;
+} | {
+    readonly kind: 'append-target-batch-dependency';
+    readonly batchId: number;
+    readonly dependencyId: number;
+    readonly source: TargetBatchDependencySource;
+    readonly valueCompletionSequence: number;
+} | {
+    readonly kind: 'seal-target-batch-activity';
+    readonly batchId: number;
+    readonly aggregateReactionSequence: number;
+    readonly authoredCarriers: readonly TargetBatchAuthoredCarrier[];
+} | {
+    readonly kind: 'report-target-batch-dependency-event';
+    readonly event: TargetBatchDependencyEvent;
+} | {
+    readonly kind: 'acknowledge-target-batch-dependency-event';
+    readonly event: TargetBatchDependencyEvent;
+} | {
+    readonly kind: 'acknowledge-identity-target-batch-dependency-event';
+    readonly identityId: number;
+    readonly event: IdentityTargetBatchDependencyEvent;
+} | {
+    readonly kind: 'transfer-next-authored-carrier-retention';
+    readonly batchId: number;
+    readonly carrierIndex: number;
+    readonly identityId: number;
+    readonly carrierSequence: number;
+} | {
+    readonly kind: 'react-to-target-batch-aggregate';
+    readonly batchId: number;
+    readonly aggregateReactionSequence: number;
+    readonly orchestrationPending: boolean;
+    readonly ownerGenerationLive: boolean;
+} | {
+    readonly kind: 'complete-target-batch-orchestration';
+    readonly batchId: number;
+    readonly aggregateReactionSequence: number;
+    readonly ownerGenerationLive: boolean;
+} | {
+    readonly kind: 'release-target-batch-activity';
+    readonly batchId: number;
+    readonly terminal: 'delivered' | 'permanently-unrunnable';
+} | {
+    readonly kind: 'acquire-pending-frame-activity';
+    readonly identityId: number;
+    readonly carrierSequence: number;
+} | {
+    readonly kind: 'release-pending-frame-activity';
+    readonly identityId: number;
+    readonly carrierSequence: number;
+};
+export type ExternalAnimationLedgerEffect = {
+    readonly kind: 'stop-physical-execution';
+    readonly identityId: number;
+    readonly executionId: number;
+} | {
+    readonly kind: 'emit-animation-cancel-listeners';
+    readonly identityId: number;
+    readonly executionId: number;
+} | {
+    readonly kind: 'emit-animation-complete-listeners';
+    readonly identityId: number;
+    readonly executionId: number;
+    readonly completionSequence: number;
+} | {
+    readonly kind: 'drain-reentrant-listener-commands';
+    readonly identityId: number;
+    readonly executionId: number;
+} | {
+    readonly kind: 'clear-public-control-slot-token-blind';
+    readonly identityId: number;
+    readonly causedByExecutionId: number;
+} | {
+    readonly kind: 'resolve-public-start-promise';
+    readonly identityId: number;
+    readonly executionId: number;
+    readonly completionSequence: number;
+} | {
+    readonly kind: 'emit-target-batch-dependency-event';
+    readonly identityId: number;
+    readonly event: IdentityTargetBatchDependencyEvent;
+} | {
+    readonly kind: 'acknowledge-authoritative-completion';
+    readonly identityId: number;
+    readonly executionId: number;
+    readonly acknowledgementSequence: number;
+} | {
+    readonly kind: 'acknowledge-authoritative-cancellation';
+    readonly identityId: number;
+    readonly executionId: number;
+    readonly acknowledgementSequence: number;
+} | {
+    readonly kind: 'release-external-animation-entry';
+    readonly identityId: number;
+    readonly executionId: number;
+} | {
+    readonly kind: 'acquire-pending-frame-activity';
+    readonly identityId: number;
+    readonly carrierSequence: number;
+} | {
+    readonly kind: 'register-target-batch-aggregate-reaction';
+    readonly batchId: number;
+    readonly aggregateReactionSequence: number;
+} | {
+    readonly kind: 'emit-target-owner-element-completion';
+    readonly batchId: number;
+} | {
+    readonly kind: 'release-target-batch-activity';
+    readonly batchId: number;
+    readonly terminal: 'delivered' | 'permanently-unrunnable';
+} | {
+    readonly kind: 'release-pending-frame-activity';
+    readonly identityId: number;
+    readonly carrierSequence: number;
+};
+export interface ExternalAnimationLedgerTransition {
+    readonly state: ExternalAnimationLedgerState;
+    readonly observation: ExternalAnimationLedgerObservation;
+    readonly orderedEffects: readonly ExternalAnimationLedgerEffect[];
+}
+export type ExternalAnimationLedgerOperation = ExternalAnimationLedgerEvent['kind'];
+export type ExternalAnimationLedgerInvariant = 'identity-id-already-retained' | 'identity-not-retained' | 'identity-authority-not-quiescent' | 'execution-id-already-retained' | 'execution-not-retained' | 'execution-state-mismatch' | 'execution-creation-sequence-mismatch' | 'execution-target-batch-dependency-already-captured' | 'public-control-slot-reference-mismatch' | 'completion-sequence-mismatch' | 'cancellation-sequence-mismatch' | 'authoritative-acknowledgement-out-of-order' | 'identity-target-batch-dependency-event-acknowledgement-out-of-order' | 'identity-target-batch-dependency-event-not-retained' | 'target-batch-dependency-reference-mismatch' | 'target-batch-id-already-retained' | 'target-batch-not-retained' | 'target-batch-dependency-id-already-retained' | 'target-batch-dependency-state-mismatch' | 'target-batch-dependency-source-mismatch' | 'target-batch-dependency-value-completion-sequence-mismatch' | 'aggregate-reaction-sequence-mismatch' | 'target-batch-event-sequence-replay-conflict' | 'target-batch-carrier-order-mismatch' | 'target-batch-carrier-retention-incomplete' | 'target-batch-reaction-state-mismatch' | 'target-batch-release-before-terminal' | 'pending-frame-activity-already-retained' | 'pending-frame-activity-sequence-out-of-order' | 'pending-frame-activity-release-order-mismatch' | 'pending-frame-activity-not-retained' | 'ledger-event-kind-unrecognized';
+export declare const EXTERNAL_ANIMATION_LEDGER_UNIMPLEMENTED: "NATIVE_MOTION_CORE_EXTERNAL_ANIMATION_LEDGER_UNIMPLEMENTED";
+export declare class ExternalAnimationLedgerUnimplementedError extends Error {
+    readonly code: "NATIVE_MOTION_CORE_EXTERNAL_ANIMATION_LEDGER_UNIMPLEMENTED";
+    readonly operation: ExternalAnimationLedgerOperation;
+    constructor(operation: ExternalAnimationLedgerOperation);
+}
+export declare const EXTERNAL_ANIMATION_LEDGER_INVARIANT: "NATIVE_MOTION_CORE_EXTERNAL_ANIMATION_LEDGER_INVARIANT";
+/** Typed fail-closed refusal for malformed, conflicting, or out-of-sequence ledger input. */
+export declare class ExternalAnimationLedgerInvariantError extends Error {
+    readonly code: "NATIVE_MOTION_CORE_EXTERNAL_ANIMATION_LEDGER_INVARIANT";
+    readonly invariant: ExternalAnimationLedgerInvariant;
+    constructor(invariant: ExternalAnimationLedgerInvariant);
+}
+export interface ExternalAnimationLedger {
+    observeState(): ExternalAnimationLedgerState;
+    observe(): ExternalAnimationLedgerObservation;
+    observeIdentity(identityId: number): ExternalAnimationIdentityObservation;
+    advance(event: ExternalAnimationLedgerEvent): ExternalAnimationLedgerTransition;
+}
+export interface CreateExternalAnimationLedgerOptions {
+    readonly graph: MotionGraph;
+    readonly initialState?: ExternalAnimationLedgerState;
+}
+export declare function initialExternalAnimationLedgerState(): ExternalAnimationLedgerState;
+export declare function createExternalAnimationLedger(options: CreateExternalAnimationLedgerOptions): ExternalAnimationLedger;
+export {};