@undefineds.co/linx 0.3.5 → 0.3.8

package/vendor/agent-runtime/dist/sync.js

@@ -0,0 +1,550 @@
+export class LinxSyncOperationError extends Error {
+    operationId;
+    operationKind;
+    constructor(operation, cause) {
+        const message = cause instanceof Error ? cause.message : String(cause);
+        super(`Sync operation failed (${operation.id}): ${message}`);
+        this.name = 'LinxSyncOperationError';
+        this.operationId = operation.id;
+        this.operationKind = operation.kind;
+        this.cause = cause;
+    }
+}
+export async function runLinxSyncOperations(operations, options) {
+    const baseContext = {
+        source: options.source,
+        target: options.target,
+        direction: options.direction ?? 'local-to-core',
+        plane: options.plane ?? 'projection',
+        authority: options.authority ?? 'core',
+        signal: options.signal,
+        now: options.now ?? (() => new Date()),
+        metadata: options.metadata,
+    };
+    const startedAt = baseContext.now().toISOString();
+    const result = {
+        source: baseContext.source,
+        target: baseContext.target,
+        direction: baseContext.direction,
+        plane: baseContext.plane,
+        authority: baseContext.authority,
+        attempted: 0,
+        applied: 0,
+        skipped: 0,
+        failed: 0,
+        failures: [],
+        startedAt,
+        completedAt: startedAt,
+        status: 'completed',
+        metadata: baseContext.metadata,
+    };
+    for (const operation of operations) {
+        throwIfSyncAborted(baseContext.signal);
+        const context = resolveOperationContext(baseContext, operation);
+        result.attempted += 1;
+        const shouldRun = operation.shouldRun ? await operation.shouldRun(context) : true;
+        if (!shouldRun) {
+            result.skipped += 1;
+            await options.onOperationSkipped?.(operation, context);
+            continue;
+        }
+        await options.onOperationStart?.(operation, context);
+        try {
+            throwIfSyncAborted(context.signal);
+            await operation.apply(context);
+            throwIfSyncAborted(context.signal);
+            result.applied += 1;
+            await options.onOperationSuccess?.(operation, context);
+        }
+        catch (cause) {
+            const error = cause instanceof LinxSyncOperationError
+                ? cause
+                : new LinxSyncOperationError(operation, cause);
+            result.failed += 1;
+            result.failures.push({
+                operationId: operation.id,
+                message: error.message,
+                failedAt: context.now().toISOString(),
+                cause: error.cause,
+            });
+            await options.onOperationError?.(operation, error, context);
+            if (!options.continueOnError) {
+                finalizeSyncResult(result, context.now().toISOString());
+                await writeSyncCheckpoint(options, result);
+                throw error;
+            }
+        }
+    }
+    finalizeSyncResult(result, baseContext.now().toISOString());
+    await writeSyncCheckpoint(options, result);
+    return result;
+}
+export async function runLinxSyncTask(options) {
+    let failed = false;
+    let failure;
+    let value;
+    const { initialMetadata: taskInitialMetadata, ...runOptions } = options;
+    const initialMetadata = typeof options.metadata === 'function' ? taskInitialMetadata : options.metadata;
+    const result = await runLinxSyncOperations([
+        {
+            id: options.operationId,
+            kind: options.kind,
+            description: options.description,
+            apply: async (context) => {
+                try {
+                    value = await options.task(context);
+                }
+                catch (error) {
+                    failed = true;
+                    failure = error;
+                    throw error;
+                }
+            },
+        },
+    ], {
+        ...runOptions,
+        metadata: initialMetadata,
+        continueOnError: true,
+    });
+    if (!failed && typeof options.metadata === 'function') {
+        result.metadata = options.metadata(value);
+    }
+    await options.onResult?.(result);
+    if (failed) {
+        throw failure;
+    }
+    return { value: value, result };
+}
+export class LinxPodSyncScope {
+    options;
+    results = [];
+    sequence = 0;
+    constructor(options) {
+        this.options = options;
+    }
+    getResults() {
+        return [...this.results];
+    }
+    getLastResult() {
+        return this.results.length > 0 ? this.results[this.results.length - 1] : null;
+    }
+    clearResults() {
+        this.results.length = 0;
+        this.sequence = 0;
+    }
+    async run(options) {
+        const initialMetadata = createLinxPodSyncMetadata({
+            action: options.action,
+            resourceBindings: resolveInitialResourceBindings(options.resourceBindings, options.refs),
+            metadata: {
+                ...this.options.metadata,
+                ...(typeof options.metadata === 'function' ? undefined : options.metadata),
+            },
+        });
+        const { value } = await runLinxSyncTask({
+            operationId: options.operationId ?? this.nextOperationId(options.action, options.subject),
+            kind: options.kind ?? 'custom',
+            description: options.description ?? `${options.action}`,
+            source: options.source ?? this.options.source,
+            target: options.target ?? this.options.target ?? 'pod',
+            direction: options.direction ?? this.options.direction ?? 'local-to-core',
+            plane: options.plane ?? this.options.plane ?? 'projection',
+            authority: options.authority ?? this.options.authority ?? 'core',
+            signal: this.options.signal,
+            now: this.options.now,
+            checkpoint: this.options.checkpoint,
+            checkpointId: this.options.checkpointId,
+            initialMetadata,
+            metadata: (value) => createLinxPodSyncMetadata({
+                action: options.action,
+                resourceBindings: mergeLinxPodSyncResourceBindings(resolveLinxPodSyncValue(options.refs, value), resolveLinxPodSyncValue(options.resourceBindings, value)),
+                metadata: {
+                    ...this.options.metadata,
+                    ...resolveLinxPodSyncValue(options.metadata, value),
+                },
+            }),
+            onOperationStart: this.options.onOperationStart,
+            onOperationSuccess: this.options.onOperationSuccess,
+            onOperationSkipped: this.options.onOperationSkipped,
+            onOperationError: this.options.onOperationError,
+            onResult: async (result) => {
+                this.results.push(result);
+                await this.options.onResult?.(result);
+                await options.onResult?.(result);
+            },
+            task: options.task,
+        });
+        return value;
+    }
+    async runOperations(options) {
+        const result = await runLinxSyncOperations(options.operations, {
+            source: options.source ?? this.options.source,
+            target: options.target ?? this.options.target ?? 'pod',
+            direction: options.direction ?? this.options.direction ?? 'local-to-core',
+            plane: options.plane ?? this.options.plane ?? 'projection',
+            authority: options.authority ?? this.options.authority ?? 'core',
+            signal: this.options.signal,
+            now: this.options.now,
+            checkpoint: this.options.checkpoint,
+            checkpointId: options.checkpointId ?? this.options.checkpointId,
+            continueOnError: options.continueOnError,
+            metadata: createLinxPodSyncMetadata({
+                action: options.action,
+                resourceBindings: mergeLinxPodSyncResourceBindings(options.refs, options.resourceBindings),
+                metadata: {
+                    ...this.options.metadata,
+                    ...options.metadata,
+                },
+            }),
+            onOperationStart: this.options.onOperationStart,
+            onOperationSuccess: this.options.onOperationSuccess,
+            onOperationSkipped: this.options.onOperationSkipped,
+            onOperationError: this.options.onOperationError,
+        });
+        this.results.push(result);
+        await this.options.onResult?.(result);
+        await options.onResult?.(result);
+        return result;
+    }
+    nextOperationId(action, subject) {
+        const timestamp = (this.options.now?.() ?? new Date()).toISOString().replace(/[:.]/g, '-');
+        return `${this.options.source}:${action}:${normalizeLinxSyncOperationSegment(subject ?? 'sync')}:${timestamp}:${++this.sequence}`;
+    }
+}
+export function createLinxPodSyncScope(options) {
+    return new LinxPodSyncScope(options);
+}
+export function createLinxPodSyncMetadata(input) {
+    const metadata = {
+        action: input.action,
+    };
+    const resourceBindings = normalizeLinxPodSyncResourceBindings(mergeLinxPodSyncResourceBindings(input.refs, input.resourceBindings));
+    if (resourceBindings) {
+        metadata.resourceBindings = resourceBindings;
+    }
+    for (const [key, value] of Object.entries(input.metadata ?? {})) {
+        setDefinedMetadataValue(metadata, key, value);
+    }
+    return metadata;
+}
+export class LinxPodSyncQueue {
+    options;
+    queue;
+    tasks = new Map();
+    sequence = 0;
+    constructor(options) {
+        this.options = options;
+        const { onResult, metadata: _metadata, ...queueOptions } = options;
+        this.queue = createLinxSyncQueue({
+            ...queueOptions,
+            onResult: async (result, task) => {
+                const podTask = this.tasks.get(task.id);
+                if (podTask) {
+                    await onResult?.(result, podTask);
+                }
+            },
+        });
+    }
+    enqueue(task) {
+        const id = task.id ?? this.nextOperationId(task.action, task.subject);
+        this.tasks.set(id, task);
+        const result = this.queue.enqueue({
+            id,
+            kind: task.kind ?? 'custom',
+            description: task.description ?? task.action,
+            source: task.source,
+            target: task.target,
+            direction: task.direction,
+            plane: task.plane,
+            authority: task.authority,
+            checkpointId: task.checkpointId,
+            metadata: createLinxPodSyncMetadata({
+                action: task.action,
+                resourceBindings: mergeLinxPodSyncResourceBindings(task.refs, task.resourceBindings),
+                metadata: {
+                    ...this.options.metadata,
+                    ...task.metadata,
+                },
+            }),
+            run: async (context) => {
+                const resolvedRefs = await task.resolveRefs?.(context);
+                const resolvedResourceBindings = await task.resolveResourceBindings?.(context);
+                const resolvedMetadata = await task.resolveMetadata?.(context);
+                if (resolvedRefs || resolvedResourceBindings || resolvedMetadata) {
+                    Object.assign(context.metadata ?? {}, createLinxPodSyncMetadata({
+                        action: task.action,
+                        resourceBindings: mergeLinxPodSyncResourceBindings(mergeLinxPodSyncResourceBindings(task.refs, task.resourceBindings), mergeLinxPodSyncResourceBindings(resolvedRefs, resolvedResourceBindings)),
+                        metadata: {
+                            ...this.options.metadata,
+                            ...task.metadata,
+                            ...resolvedMetadata,
+                        },
+                    }));
+                }
+                await task.run(context);
+            },
+        });
+        void result.finally(() => {
+            this.tasks.delete(id);
+        });
+        return result;
+    }
+    async flush() {
+        await this.queue.flush();
+    }
+    getResults() {
+        return this.queue.getResults();
+    }
+    nextOperationId(action, subject) {
+        const timestamp = (this.options.now?.() ?? new Date()).toISOString().replace(/[:.]/g, '-');
+        return `${this.options.source}:${action}:${normalizeLinxSyncOperationSegment(subject ?? 'sync')}:${timestamp}:${++this.sequence}`;
+    }
+}
+export function createLinxPodSyncQueue(options) {
+    return new LinxPodSyncQueue(options);
+}
+export class LinxSyncQueue {
+    options;
+    tail = Promise.resolve();
+    results = [];
+    constructor(options) {
+        this.options = options;
+    }
+    enqueue(task) {
+        const operation = {
+            id: task.id,
+            kind: task.kind ?? 'custom',
+            description: task.description,
+            source: task.source,
+            target: task.target,
+            direction: task.direction,
+            plane: task.plane,
+            authority: task.authority,
+            apply: task.run,
+        };
+        const next = this.tail
+            .then(() => this.runTask(task, operation), () => this.runTask(task, operation))
+            .catch((error) => {
+            this.options.onError?.(error);
+            return null;
+        });
+        this.tail = next;
+        return next;
+    }
+    async flush() {
+        await this.tail;
+    }
+    getResults() {
+        return [...this.results];
+    }
+    async runTask(task, operation) {
+        const result = await runLinxSyncOperations([operation], {
+            ...this.options,
+            source: task.source ?? this.options.source,
+            target: task.target ?? this.options.target,
+            direction: task.direction ?? this.options.direction,
+            plane: task.plane ?? this.options.plane,
+            authority: task.authority ?? this.options.authority,
+            checkpointId: task.checkpointId ?? task.id,
+            metadata: {
+                ...this.options.metadata,
+                ...task.metadata,
+                syncTask: task.id,
+                ...(task.description ? { syncTaskDescription: task.description } : {}),
+            },
+        });
+        this.results.push(result);
+        await this.options.onResult?.(result, task);
+        return result;
+    }
+}
+export function createLinxSyncQueue(options) {
+    return new LinxSyncQueue(options);
+}
+export function createInMemoryLinxSyncCheckpointStore(initial = []) {
+    const checkpoints = new Map();
+    for (const checkpoint of initial) {
+        checkpoints.set(checkpoint.id, checkpoint);
+    }
+    return {
+        writeCheckpoint(checkpoint) {
+            checkpoints.set(checkpoint.id, checkpoint);
+        },
+        readCheckpoint(id) {
+            return checkpoints.get(id) ?? null;
+        },
+        listCheckpoints(query) {
+            return [...checkpoints.values()].filter((checkpoint) => matchesLinxSyncCheckpointQuery(checkpoint, query));
+        },
+        deleteCheckpoint(id) {
+            checkpoints.delete(id);
+        },
+    };
+}
+export function createLinxSyncCheckpoint(id, result, metadata) {
+    return {
+        id,
+        source: result.source,
+        target: result.target,
+        direction: result.direction,
+        plane: result.plane,
+        authority: result.authority,
+        status: result.status,
+        attempted: result.attempted,
+        applied: result.applied,
+        skipped: result.skipped,
+        failed: result.failed,
+        failures: result.failures,
+        startedAt: result.startedAt,
+        completedAt: result.completedAt,
+        metadata,
+    };
+}
+export async function readLinxSyncCheckpoint(store, id) {
+    return store.readCheckpoint ? await store.readCheckpoint(id) : null;
+}
+export async function listLinxSyncCheckpoints(store, query) {
+    if (store.listCheckpoints) {
+        return store.listCheckpoints(query);
+    }
+    return [];
+}
+export async function deleteLinxSyncCheckpoint(store, id) {
+    await store.deleteCheckpoint?.(id);
+}
+export function matchesLinxSyncCheckpointQuery(checkpoint, query = {}) {
+    if (query.source !== undefined && checkpoint.source !== query.source)
+        return false;
+    if (query.target !== undefined && checkpoint.target !== query.target)
+        return false;
+    if (query.direction !== undefined && checkpoint.direction !== query.direction)
+        return false;
+    if (query.plane !== undefined && checkpoint.plane !== query.plane)
+        return false;
+    if (query.authority !== undefined && checkpoint.authority !== query.authority)
+        return false;
+    if (query.status !== undefined) {
+        const statuses = Array.isArray(query.status) ? query.status : [query.status];
+        if (!statuses.includes(checkpoint.status))
+            return false;
+    }
+    if (query.metadata) {
+        for (const [key, value] of Object.entries(query.metadata)) {
+            if (!matchesLinxSyncMetadataValue(readLinxSyncMetadataValue(checkpoint.metadata, key), value))
+                return false;
+        }
+    }
+    return true;
+}
+function readLinxSyncMetadataValue(metadata, key) {
+    if (key === 'resourceBindings') {
+        return metadata?.resourceBindings ?? metadata?.refs;
+    }
+    if (key === 'refs') {
+        return metadata?.refs ?? metadata?.resourceBindings;
+    }
+    return metadata?.[key];
+}
+function matchesLinxSyncMetadataValue(actual, expected) {
+    if (expected && typeof expected === 'object' && !Array.isArray(expected)) {
+        if (!actual || typeof actual !== 'object' || Array.isArray(actual)) {
+            return false;
+        }
+        const actualRecord = actual;
+        return Object.entries(expected)
+            .every(([key, value]) => matchesLinxSyncMetadataValue(actualRecord[key], value));
+    }
+    return actual === expected;
+}
+export function isPendingLinxSyncCheckpoint(checkpoint) {
+    return checkpoint.status === 'failed' || checkpoint.status === 'partial';
+}
+function finalizeSyncResult(result, completedAt) {
+    result.completedAt = completedAt;
+    result.status = result.failed === 0
+        ? 'completed'
+        : result.applied > 0 || result.skipped > 0
+            ? 'partial'
+            : 'failed';
+}
+async function writeSyncCheckpoint(options, result) {
+    if (!options.checkpoint) {
+        return;
+    }
+    const checkpointId = typeof options.checkpointId === 'function'
+        ? options.checkpointId(result)
+        : options.checkpointId ?? `${result.source}:${result.target}:${result.plane}`;
+    await options.checkpoint.writeCheckpoint(createLinxSyncCheckpoint(checkpointId, result, options.metadata));
+}
+function resolveOperationContext(base, operation) {
+    return {
+        ...base,
+        source: operation.source ?? base.source,
+        target: operation.target ?? base.target,
+        direction: operation.direction ?? base.direction,
+        plane: operation.plane ?? base.plane,
+        authority: operation.authority ?? base.authority,
+    };
+}
+function resolveLinxPodSyncValue(value, input) {
+    return typeof value === 'function'
+        ? value(input)
+        : value;
+}
+function resolveInitialResourceBindings(resourceBindings, refs) {
+    return mergeLinxPodSyncResourceBindings(typeof refs === 'function' ? undefined : refs, typeof resourceBindings === 'function' ? undefined : resourceBindings);
+}
+function mergeLinxPodSyncResourceBindings(base, override) {
+    if (!base && !override) {
+        return undefined;
+    }
+    const merged = { ...(base ?? {}) };
+    for (const [name, ref] of Object.entries(override ?? {})) {
+        if (!ref) {
+            merged[name] = ref;
+            continue;
+        }
+        merged[name] = {
+            ...(merged[name] ?? {}),
+            ...ref,
+        };
+    }
+    return merged;
+}
+function normalizeLinxPodSyncResourceBindings(resourceBindings) {
+    const normalized = {};
+    for (const [name, ref] of Object.entries(resourceBindings ?? {})) {
+        if (!ref)
+            continue;
+        const next = {};
+        if (ref.uri !== undefined && ref.uri !== null) {
+            next.uri = ref.uri;
+        }
+        if (ref.local !== undefined && ref.local !== null) {
+            next.local = ref.local;
+        }
+        if (Object.keys(next).length > 0) {
+            normalized[name] = next;
+        }
+    }
+    return Object.keys(normalized).length > 0 ? normalized : undefined;
+}
+function setDefinedMetadataValue(metadata, key, value) {
+    if (value !== undefined && value !== null) {
+        metadata[key] = value;
+    }
+}
+function normalizeLinxSyncOperationSegment(value) {
+    return value.replace(/[:\s]+/g, '-');
+}
+function throwIfSyncAborted(signal) {
+    if (!signal?.aborted) {
+        return;
+    }
+    if (signal.reason instanceof Error) {
+        throw signal.reason;
+    }
+    const error = new Error('The sync operation was aborted.');
+    error.name = 'AbortError';
+    throw error;
+}

package/vendor/agent-runtime/dist/thread-reconciler-controller.d.ts

@@ -0,0 +1,58 @@
+import { type ReconcileDecision, type ReconcileDecisionSummary, type ReconcileThreadEventInput, type ThreadControlEvent, type ThreadPolicy, type ThreadPolicyKind, type WakeJob } from './reconciler.js';
+import { type WakeJobExecutionRecord, type WakeJobExecutionRecordSummary, type WakeJobSchedulerSnapshot, type WakeJobSchedulerSnapshotSummary } from './wake-scheduler.js';
+type MaybePromise<T> = T | Promise<T>;
+export interface ThreadWakeJobContext {
+    job: WakeJob;
+    record: WakeJobExecutionRecord;
+    decision: ReconcileDecision;
+    decisionSummary: ReconcileDecisionSummary;
+}
+export type ThreadWakeJobHandler = (context: ThreadWakeJobContext) => MaybePromise<unknown>;
+export interface ThreadReconcilerControllerOptions {
+    policy: ThreadPolicyKind | ThreadPolicy;
+    handleWakeJob: ThreadWakeJobHandler;
+    concurrency?: number;
+    autoStart?: boolean;
+    now?: () => Date;
+    onDecision?: (decision: ReconcileDecisionSummary) => void;
+    onWakeJobQueued?: (record: WakeJobExecutionRecord, decision: ReconcileDecisionSummary) => void;
+    onWakeJobStarted?: (record: WakeJobExecutionRecord, decision: ReconcileDecisionSummary) => void;
+    onWakeJobCompleted?: (record: WakeJobExecutionRecord, decision: ReconcileDecisionSummary) => void;
+    onWakeJobFailed?: (record: WakeJobExecutionRecord, decision: ReconcileDecisionSummary) => void;
+}
+export interface ThreadReconcilerDispatchOptions extends Omit<ReconcileThreadEventInput, 'policy' | 'event'> {
+}
+export interface ThreadReconcilerDispatchResult {
+    decision: ReconcileDecision;
+    summary: ReconcileDecisionSummary;
+    wakeRecords: WakeJobExecutionRecord[];
+    wakeRecordSummaries: WakeJobExecutionRecordSummary[];
+}
+export interface ThreadReconcilerDrainResult {
+    scheduler: WakeJobSchedulerSnapshot;
+    schedulerSummary: WakeJobSchedulerSnapshotSummary;
+}
+export interface ThreadReconcilerDispatchAndDrainResult extends ThreadReconcilerDispatchResult, ThreadReconcilerDrainResult {
+}
+export interface ThreadReconcilerDecisionResult {
+    decision: ReconcileDecision;
+    summary: ReconcileDecisionSummary;
+}
+export interface RunThreadReconcilerCycleOptions extends Omit<ThreadReconcilerControllerOptions, 'autoStart'> {
+    event: ThreadControlEvent;
+    dispatchOptions?: ThreadReconcilerDispatchOptions;
+    onDispatched?: (result: ThreadReconcilerDispatchResult) => MaybePromise<void>;
+}
+export interface ThreadReconcilerController {
+    dispatch(event: ThreadControlEvent, options?: ThreadReconcilerDispatchOptions): ThreadReconcilerDispatchResult;
+    dispatchAndDrain(event: ThreadControlEvent, options?: ThreadReconcilerDispatchOptions): Promise<ThreadReconcilerDispatchAndDrainResult>;
+    startAndDrain(): Promise<ThreadReconcilerDrainResult>;
+    start(): void;
+    stop(): void;
+    drain(): Promise<void>;
+    snapshot(): WakeJobSchedulerSnapshot;
+}
+export declare function createThreadReconcilerController(options: ThreadReconcilerControllerOptions): ThreadReconcilerController;
+export declare function decideThreadControlEvent(input: ReconcileThreadEventInput): ThreadReconcilerDecisionResult;
+export declare function runThreadReconcilerCycle(options: RunThreadReconcilerCycleOptions): Promise<ThreadReconcilerDispatchAndDrainResult>;
+export {};