@undefineds.co/linx 0.3.4 → 0.3.7

package/vendor/agent-runtime/dist/sync.d.ts

@@ -0,0 +1,271 @@
+export type LinxSyncAuthority = 'local-runtime' | 'core';
+export type LinxSyncDirection = 'local-to-core' | 'core-to-local' | 'bidirectional';
+export type LinxSyncPlane = 'runtime-log' | 'projection' | 'control-plane' | 'recovery';
+type MaybePromise<T> = T | Promise<T>;
+export type LinxSyncOperationKind = 'prepare' | 'insert' | 'upsert' | 'update' | 'delete' | 'checkpoint' | 'custom';
+export interface LinxSyncContext {
+    source: string;
+    target: string;
+    direction: LinxSyncDirection;
+    plane: LinxSyncPlane;
+    authority: LinxSyncAuthority;
+    signal?: AbortSignal;
+    now: () => Date;
+    metadata?: Record<string, unknown>;
+}
+export interface LinxSyncOperation {
+    id: string;
+    kind?: LinxSyncOperationKind;
+    description?: string;
+    source?: string;
+    target?: string;
+    direction?: LinxSyncDirection;
+    plane?: LinxSyncPlane;
+    authority?: LinxSyncAuthority;
+    idempotencyKey?: string;
+    shouldRun?: (context: LinxSyncContext) => boolean | Promise<boolean>;
+    apply: (context: LinxSyncContext) => void | Promise<void>;
+}
+export interface LinxSyncOperationFailure {
+    operationId: string;
+    message: string;
+    failedAt?: string;
+    cause?: unknown;
+}
+export interface LinxSyncRunResult {
+    source: string;
+    target: string;
+    direction: LinxSyncDirection;
+    plane: LinxSyncPlane;
+    authority: LinxSyncAuthority;
+    attempted: number;
+    applied: number;
+    skipped: number;
+    failed: number;
+    failures: LinxSyncOperationFailure[];
+    startedAt: string;
+    completedAt: string;
+    status: 'completed' | 'partial' | 'failed';
+    metadata?: Record<string, unknown>;
+}
+export interface LinxSyncRunOptions {
+    source: string;
+    target: string;
+    direction?: LinxSyncDirection;
+    plane?: LinxSyncPlane;
+    authority?: LinxSyncAuthority;
+    signal?: AbortSignal;
+    now?: () => Date;
+    metadata?: Record<string, unknown>;
+    continueOnError?: boolean;
+    checkpoint?: LinxSyncCheckpointStore;
+    checkpointId?: string | ((result: LinxSyncRunResult) => string);
+    onOperationStart?: (operation: LinxSyncOperation, context: LinxSyncContext) => void | Promise<void>;
+    onOperationSuccess?: (operation: LinxSyncOperation, context: LinxSyncContext) => void | Promise<void>;
+    onOperationSkipped?: (operation: LinxSyncOperation, context: LinxSyncContext) => void | Promise<void>;
+    onOperationError?: (operation: LinxSyncOperation, error: LinxSyncOperationError, context: LinxSyncContext) => void | Promise<void>;
+}
+export interface LinxSyncTaskOptions<T> extends Omit<LinxSyncRunOptions, 'continueOnError' | 'metadata'> {
+    operationId: string;
+    kind?: LinxSyncOperationKind;
+    description?: string;
+    initialMetadata?: Record<string, unknown>;
+    metadata?: Record<string, unknown> | ((value: T) => Record<string, unknown>);
+    onResult?: (result: LinxSyncRunResult) => void | Promise<void>;
+    task: (context: LinxSyncContext) => T | Promise<T>;
+}
+export interface LinxSyncTaskRun<T> {
+    value: T;
+    result: LinxSyncRunResult;
+}
+export interface LinxSyncCheckpoint {
+    id: string;
+    source: string;
+    target: string;
+    direction: LinxSyncDirection;
+    plane: LinxSyncPlane;
+    authority: LinxSyncAuthority;
+    status: LinxSyncRunResult['status'];
+    attempted: number;
+    applied: number;
+    skipped: number;
+    failed: number;
+    failures: LinxSyncOperationFailure[];
+    startedAt: string;
+    completedAt: string;
+    metadata?: Record<string, unknown>;
+}
+export interface LinxSyncCheckpointQuery {
+    source?: string;
+    target?: string;
+    direction?: LinxSyncDirection;
+    plane?: LinxSyncPlane;
+    authority?: LinxSyncAuthority;
+    status?: LinxSyncRunResult['status'] | LinxSyncRunResult['status'][];
+    metadata?: Record<string, unknown>;
+}
+export interface LinxSyncCheckpointStore {
+    writeCheckpoint: (checkpoint: LinxSyncCheckpoint) => void | Promise<void>;
+    readCheckpoint?: (id: string) => LinxSyncCheckpoint | null | Promise<LinxSyncCheckpoint | null>;
+    listCheckpoints?: (query?: LinxSyncCheckpointQuery) => LinxSyncCheckpoint[] | Promise<LinxSyncCheckpoint[]>;
+    deleteCheckpoint?: (id: string) => void | Promise<void>;
+}
+export declare class LinxSyncOperationError extends Error {
+    readonly operationId: string;
+    readonly operationKind?: LinxSyncOperationKind;
+    constructor(operation: Pick<LinxSyncOperation, 'id' | 'kind'>, cause: unknown);
+}
+export declare function runLinxSyncOperations(operations: Iterable<LinxSyncOperation>, options: LinxSyncRunOptions): Promise<LinxSyncRunResult>;
+export declare function runLinxSyncTask<T>(options: LinxSyncTaskOptions<T>): Promise<LinxSyncTaskRun<T>>;
+/**
+ * Per-run sync ledger binding between a local/runtime key and a Pod resource.
+ *
+ * These bindings live on sync run/checkpoint metadata and are scoped by the
+ * top-level sync `source`; they are not durable RDF predicates on business
+ * resources. Multiple apps can bind the same Pod URI in separate checkpoints
+ * without writing app-specific state onto the shared resource.
+ */
+export interface LinxPodSyncResourceBinding {
+    uri?: string | null;
+    local?: string | null;
+}
+export type LinxPodSyncResourceBindings = Record<string, LinxPodSyncResourceBinding | null | undefined>;
+/** @deprecated Use LinxPodSyncResourceBinding. */
+export type LinxPodSyncResourceRef = LinxPodSyncResourceBinding;
+/** @deprecated Use LinxPodSyncResourceBindings. */
+export type LinxPodSyncResourceRefs = LinxPodSyncResourceBindings;
+export interface LinxPodSyncMetadataInput {
+    action: string;
+    resourceBindings?: LinxPodSyncResourceBindings | null;
+    /** @deprecated Use resourceBindings. */
+    refs?: LinxPodSyncResourceBindings | null;
+    metadata?: Record<string, unknown> | null;
+}
+export type LinxPodSyncValueFactory<T, TValue> = TValue | ((value: T) => TValue);
+export interface LinxPodSyncScopeOptions extends Omit<LinxSyncRunOptions, 'continueOnError' | 'metadata' | 'target'> {
+    target?: string;
+    metadata?: Record<string, unknown>;
+    onResult?: (result: LinxSyncRunResult) => void | Promise<void>;
+}
+export interface LinxPodSyncTaskOptions<T> {
+    action: string;
+    kind?: LinxSyncOperationKind;
+    description?: string;
+    operationId?: string;
+    subject?: string | null;
+    source?: string;
+    target?: string;
+    direction?: LinxSyncDirection;
+    plane?: LinxSyncPlane;
+    authority?: LinxSyncAuthority;
+    resourceBindings?: LinxPodSyncValueFactory<T, LinxPodSyncResourceBindings | null | undefined>;
+    /** @deprecated Use resourceBindings. */
+    refs?: LinxPodSyncValueFactory<T, LinxPodSyncResourceBindings | null | undefined>;
+    metadata?: LinxPodSyncValueFactory<T, Record<string, unknown> | null | undefined>;
+    onResult?: (result: LinxSyncRunResult) => void | Promise<void>;
+    task: (context: LinxSyncContext) => T | Promise<T>;
+}
+export interface LinxPodSyncOperationsOptions {
+    action: string;
+    operations: Iterable<LinxSyncOperation>;
+    source?: string;
+    target?: string;
+    direction?: LinxSyncDirection;
+    plane?: LinxSyncPlane;
+    authority?: LinxSyncAuthority;
+    resourceBindings?: LinxPodSyncResourceBindings | null;
+    /** @deprecated Use resourceBindings. */
+    refs?: LinxPodSyncResourceBindings | null;
+    metadata?: Record<string, unknown> | null;
+    continueOnError?: boolean;
+    checkpointId?: string | ((result: LinxSyncRunResult) => string);
+    onResult?: (result: LinxSyncRunResult) => void | Promise<void>;
+}
+export interface LinxPodSyncQueueTask {
+    id?: string;
+    action: string;
+    kind?: LinxSyncOperationKind;
+    description?: string;
+    subject?: string | null;
+    source?: string;
+    target?: string;
+    direction?: LinxSyncDirection;
+    plane?: LinxSyncPlane;
+    authority?: LinxSyncAuthority;
+    checkpointId?: string;
+    resourceBindings?: LinxPodSyncResourceBindings | null;
+    resolveResourceBindings?: (context: LinxSyncContext) => MaybePromise<LinxPodSyncResourceBindings | null | undefined>;
+    /** @deprecated Use resourceBindings. */
+    refs?: LinxPodSyncResourceBindings | null;
+    /** @deprecated Use resolveResourceBindings. */
+    resolveRefs?: (context: LinxSyncContext) => MaybePromise<LinxPodSyncResourceBindings | null | undefined>;
+    metadata?: Record<string, unknown> | null;
+    resolveMetadata?: (context: LinxSyncContext) => MaybePromise<Record<string, unknown> | null | undefined>;
+    run: (context: LinxSyncContext) => void | Promise<void>;
+}
+export interface LinxPodSyncQueueOptions extends Omit<LinxSyncQueueOptions, 'metadata' | 'onResult'> {
+    metadata?: Record<string, unknown>;
+    onResult?: (result: LinxSyncRunResult, task: LinxPodSyncQueueTask) => void | Promise<void>;
+}
+export declare class LinxPodSyncScope {
+    private readonly options;
+    private readonly results;
+    private sequence;
+    constructor(options: LinxPodSyncScopeOptions);
+    getResults(): LinxSyncRunResult[];
+    getLastResult(): LinxSyncRunResult | null;
+    clearResults(): void;
+    run<T>(options: LinxPodSyncTaskOptions<T>): Promise<T>;
+    runOperations(options: LinxPodSyncOperationsOptions): Promise<LinxSyncRunResult>;
+    private nextOperationId;
+}
+export declare function createLinxPodSyncScope(options: LinxPodSyncScopeOptions): LinxPodSyncScope;
+export declare function createLinxPodSyncMetadata(input: LinxPodSyncMetadataInput): Record<string, unknown>;
+export declare class LinxPodSyncQueue {
+    private readonly options;
+    private readonly queue;
+    private readonly tasks;
+    private sequence;
+    constructor(options: LinxPodSyncQueueOptions);
+    enqueue(task: LinxPodSyncQueueTask): Promise<LinxSyncRunResult | null>;
+    flush(): Promise<void>;
+    getResults(): LinxSyncRunResult[];
+    private nextOperationId;
+}
+export declare function createLinxPodSyncQueue(options: LinxPodSyncQueueOptions): LinxPodSyncQueue;
+export interface LinxSyncQueueTask {
+    id: string;
+    kind?: LinxSyncOperationKind;
+    description?: string;
+    source?: string;
+    target?: string;
+    direction?: LinxSyncDirection;
+    plane?: LinxSyncPlane;
+    authority?: LinxSyncAuthority;
+    checkpointId?: string;
+    metadata?: Record<string, unknown>;
+    run: (context: LinxSyncContext) => void | Promise<void>;
+}
+export interface LinxSyncQueueOptions extends Omit<LinxSyncRunOptions, 'continueOnError'> {
+    onError?: (error: unknown) => void;
+    onResult?: (result: LinxSyncRunResult, task: LinxSyncQueueTask) => void | Promise<void>;
+}
+export declare class LinxSyncQueue {
+    private readonly options;
+    private tail;
+    private readonly results;
+    constructor(options: LinxSyncQueueOptions);
+    enqueue(task: LinxSyncQueueTask): Promise<LinxSyncRunResult | null>;
+    flush(): Promise<void>;
+    getResults(): LinxSyncRunResult[];
+    private runTask;
+}
+export declare function createLinxSyncQueue(options: LinxSyncQueueOptions): LinxSyncQueue;
+export declare function createInMemoryLinxSyncCheckpointStore(initial?: Iterable<LinxSyncCheckpoint>): Required<LinxSyncCheckpointStore>;
+export declare function createLinxSyncCheckpoint(id: string, result: LinxSyncRunResult, metadata?: Record<string, unknown>): LinxSyncCheckpoint;
+export declare function readLinxSyncCheckpoint(store: LinxSyncCheckpointStore, id: string): Promise<LinxSyncCheckpoint | null>;
+export declare function listLinxSyncCheckpoints(store: LinxSyncCheckpointStore, query?: LinxSyncCheckpointQuery): Promise<LinxSyncCheckpoint[]>;
+export declare function deleteLinxSyncCheckpoint(store: LinxSyncCheckpointStore, id: string): Promise<void>;
+export declare function matchesLinxSyncCheckpointQuery(checkpoint: LinxSyncCheckpoint, query?: LinxSyncCheckpointQuery): boolean;
+export declare function isPendingLinxSyncCheckpoint(checkpoint: LinxSyncCheckpoint): boolean;
+export {};