@relayfile/adapter-core 0.1.20 → 0.2.1

package/dist/src/atomic-index/index.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Optimistic compare-and-swap (CAS) upsert for `_index.json` files.
+ *
+ * Concurrent ingestions can race when the read-modify-write pattern
+ * `read existing rows -> upsert -> write` is not atomic: two writers read
+ * the same baseline, each compute their own merged result, and the second
+ * write silently overwrites the first row.
+ *
+ * The helper reads both content and the file revision (when the VFS
+ * exposes that metadata), submits a write tagged with `baseRevision`, and
+ * retries the read-merge-write loop on conflict. Backends without revision
+ * support degrade to plain read-modify-write — the race remains in those
+ * legacy backends but is not regressed by this helper.
+ *
+ * This module is generic — it deliberately knows nothing about github,
+ * linear, notion, or any specific record schema. Each adapter wires it up
+ * with its own parse / merge / serialize and (optionally) a VfsLike shim
+ * around its concrete client.
+ */
+/**
+ * Minimal duck-typed VFS contract the atomic upsert helper consumes.
+ *
+ * Adapters whose underlying client uses a single-input shape (e.g. the
+ * `RelayFileClient.writeFile({ workspaceId, path, ... })` style used by
+ * linear and notion) can satisfy this contract by wrapping the client in
+ * a small shim that flattens the call to `(path, content, options)`.
+ */
+export interface VfsLike {
+    exists?(path: string): Promise<boolean> | boolean;
+    get?(path: string): Promise<unknown> | unknown;
+    has?(path: string): Promise<boolean> | boolean;
+    put?(path: string, content: string, options?: {
+        baseRevision?: string;
+    }): Promise<unknown> | unknown;
+    read?(path: string): Promise<unknown> | unknown;
+    readFile?(path: string): Promise<unknown> | unknown;
+    set?(path: string, content: string, options?: {
+        baseRevision?: string;
+    }): Promise<unknown> | unknown;
+    stat?(path: string): Promise<unknown> | unknown;
+    upsert?(path: string, content: string, options?: {
+        baseRevision?: string;
+    }): Promise<unknown> | unknown;
+    write?(path: string, content: string, options?: {
+        baseRevision?: string;
+    }): Promise<unknown> | unknown;
+    writeFile?(path: string, content: string, options?: {
+        baseRevision?: string;
+    }): Promise<unknown> | unknown;
+}
+export interface AtomicUpsertOptions {
+    /**
+     * Maximum number of CAS attempts before throwing
+     * {@link AtomicIndexExhaustedError}. Defaults to 5.
+     */
+    maxAttempts?: number;
+    /**
+     * Linear backoff base in milliseconds. Each retry waits
+     * `baseDelayMs * attemptNumber`. Defaults to 50ms.
+     */
+    baseDelayMs?: number;
+    /**
+     * Optional sleep override, primarily exposed for tests so they don't have
+     * to wait on real timers.
+     */
+    sleep?: (ms: number) => Promise<void>;
+}
+export interface AtomicReadResult<TContent> {
+    content: TContent | undefined;
+    revision: string;
+}
+export declare class AtomicIndexExhaustedError extends Error {
+    readonly path: string;
+    readonly attempts: number;
+    constructor(path: string, attempts: number, cause?: unknown);
+}
+/**
+ * Read a text file plus its revision from the VFS.
+ *
+ * - If the VFS reader returns `{ content, revision }`, both are surfaced.
+ * - If the reader returns a plain string, revision falls back to `"0"`
+ *   (sentinel meaning "no prior revision known").
+ * - If the file is missing, `content` is `undefined` and revision is `"0"`.
+ */
+export declare function readIndexWithRevision(vfs: VfsLike, path: string): Promise<AtomicReadResult<string>>;
+/**
+ * Write a text file via any of the writer aliases the VFS exposes, passing
+ * `baseRevision` so revision-aware backends can perform a compare-and-swap.
+ *
+ * The third argument is positional rather than an options bag because the
+ * majority of legacy VFS shims spread the call as `(path, content, ...rest)`
+ * and ignore extra positional args; switching to an object would silently
+ * regress them.
+ */
+export declare function writeIndexWithRevision(vfs: VfsLike, path: string, content: string, baseRevision: string): Promise<void>;
+/**
+ * Detect a relayfile / VFS revision-conflict error without taking a hard
+ * dependency on the SDK error class — we duck-type on the standard shapes:
+ *
+ * - `RevisionConflictError` from `@relayfile/sdk` (`name === 'RevisionConflictError'`).
+ * - HTTP 409 responses surfaced as plain Errors with a `status` field.
+ * - Errors carrying a `code === 'revision_conflict'` field.
+ */
+export declare function isConflictError(error: unknown): boolean;
+/**
+ * Upsert a JSON-encoded `_index.json` file using optimistic CAS retries.
+ *
+ * The caller supplies `parse` (string -> rows), `merge` (rows -> rows), and
+ * `serialize` (rows -> bytes). Each attempt re-reads the existing rows, runs
+ * `merge` against them (so concurrent rows added by another writer survive),
+ * and writes with the just-observed revision as `baseRevision`. On conflict
+ * we back off linearly and try again, up to {@link AtomicUpsertOptions.maxAttempts}.
+ */
+export declare function upsertIndexAtomic<TRow>(vfs: VfsLike, path: string, parse: (content: string | undefined) => TRow[], merge: (rows: TRow[]) => TRow[], serialize: (rows: TRow[]) => string, options?: AtomicUpsertOptions): Promise<{
+    existedAtWrite: boolean;
+}>;
+//# sourceMappingURL=index.d.ts.map

package/dist/src/atomic-index/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/atomic-index/index.ts"],"names":[],"mappings":"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"}

package/dist/src/atomic-index/index.js

@@ -0,0 +1,168 @@
+/**
+ * Optimistic compare-and-swap (CAS) upsert for `_index.json` files.
+ *
+ * Concurrent ingestions can race when the read-modify-write pattern
+ * `read existing rows -> upsert -> write` is not atomic: two writers read
+ * the same baseline, each compute their own merged result, and the second
+ * write silently overwrites the first row.
+ *
+ * The helper reads both content and the file revision (when the VFS
+ * exposes that metadata), submits a write tagged with `baseRevision`, and
+ * retries the read-merge-write loop on conflict. Backends without revision
+ * support degrade to plain read-modify-write — the race remains in those
+ * legacy backends but is not regressed by this helper.
+ *
+ * This module is generic — it deliberately knows nothing about github,
+ * linear, notion, or any specific record schema. Each adapter wires it up
+ * with its own parse / merge / serialize and (optionally) a VfsLike shim
+ * around its concrete client.
+ */
+const DEFAULT_MAX_ATTEMPTS = 5;
+const DEFAULT_BASE_DELAY_MS = 50;
+export class AtomicIndexExhaustedError extends Error {
+    path;
+    attempts;
+    constructor(path, attempts, cause) {
+        super(`atomic index upsert exceeded ${attempts} attempts for ${path}` +
+            (cause instanceof Error ? `: ${cause.message}` : ''));
+        this.name = 'AtomicIndexExhaustedError';
+        this.path = path;
+        this.attempts = attempts;
+        if (cause !== undefined) {
+            // Preserve the underlying cause for diagnostics without forcing
+            // dependents to introspect a bespoke field.
+            this.cause = cause;
+        }
+    }
+}
+/**
+ * Read a text file plus its revision from the VFS.
+ *
+ * - If the VFS reader returns `{ content, revision }`, both are surfaced.
+ * - If the reader returns a plain string, revision falls back to `"0"`
+ *   (sentinel meaning "no prior revision known").
+ * - If the file is missing, `content` is `undefined` and revision is `"0"`.
+ */
+export async function readIndexWithRevision(vfs, path) {
+    for (const reader of [vfs.readFile, vfs.read, vfs.get]) {
+        if (!reader) {
+            continue;
+        }
+        try {
+            const value = await reader.call(vfs, path);
+            if (value === null || value === undefined) {
+                continue;
+            }
+            if (typeof value === 'string') {
+                return { content: value, revision: '0' };
+            }
+            if (typeof value === 'object') {
+                const record = value;
+                const content = typeof record.content === 'string' ? record.content : undefined;
+                const revision = typeof record.revision === 'string' ? record.revision : '0';
+                if (content !== undefined) {
+                    return { content, revision };
+                }
+            }
+        }
+        catch {
+            // A throwing reader should not abort the loop — fall through to the
+            // next available reader so we still surface text from working backends.
+            continue;
+        }
+    }
+    return { content: undefined, revision: '0' };
+}
+/**
+ * Write a text file via any of the writer aliases the VFS exposes, passing
+ * `baseRevision` so revision-aware backends can perform a compare-and-swap.
+ *
+ * The third argument is positional rather than an options bag because the
+ * majority of legacy VFS shims spread the call as `(path, content, ...rest)`
+ * and ignore extra positional args; switching to an object would silently
+ * regress them.
+ */
+export async function writeIndexWithRevision(vfs, path, content, baseRevision) {
+    const writer = vfs.writeFile ?? vfs.write ?? vfs.put ?? vfs.set ?? vfs.upsert;
+    if (!writer) {
+        throw new Error('VFS object must expose one of writeFile(path, content), write(path, content), put(path, content), set(path, content), or upsert(path, content).');
+    }
+    // Pass `baseRevision` as a 3rd positional options arg so revision-aware
+    // VFS shims (e.g. relayfile-client) can perform a CAS write. Legacy shims
+    // ignore the extra positional arg, so this is safe.
+    const variadicWriter = writer;
+    await variadicWriter.call(vfs, path, content, { baseRevision });
+}
+/**
+ * Detect a relayfile / VFS revision-conflict error without taking a hard
+ * dependency on the SDK error class — we duck-type on the standard shapes:
+ *
+ * - `RevisionConflictError` from `@relayfile/sdk` (`name === 'RevisionConflictError'`).
+ * - HTTP 409 responses surfaced as plain Errors with a `status` field.
+ * - Errors carrying a `code === 'revision_conflict'` field.
+ */
+export function isConflictError(error) {
+    if (!error || typeof error !== 'object') {
+        return false;
+    }
+    const candidate = error;
+    if (candidate.name === 'RevisionConflictError') {
+        return true;
+    }
+    if (candidate.status === 409 || candidate.statusCode === 409) {
+        return true;
+    }
+    if (candidate.code === 'revision_conflict') {
+        return true;
+    }
+    return false;
+}
+/**
+ * Upsert a JSON-encoded `_index.json` file using optimistic CAS retries.
+ *
+ * The caller supplies `parse` (string -> rows), `merge` (rows -> rows), and
+ * `serialize` (rows -> bytes). Each attempt re-reads the existing rows, runs
+ * `merge` against them (so concurrent rows added by another writer survive),
+ * and writes with the just-observed revision as `baseRevision`. On conflict
+ * we back off linearly and try again, up to {@link AtomicUpsertOptions.maxAttempts}.
+ */
+export async function upsertIndexAtomic(vfs, path, parse, merge, serialize, options = {}) {
+    const maxAttempts = options.maxAttempts ?? DEFAULT_MAX_ATTEMPTS;
+    const baseDelayMs = options.baseDelayMs ?? DEFAULT_BASE_DELAY_MS;
+    const sleep = options.sleep ?? defaultSleep;
+    if (maxAttempts < 1) {
+        throw new Error('upsertIndexAtomic: maxAttempts must be >= 1');
+    }
+    let lastError;
+    for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
+        const { content, revision } = await readIndexWithRevision(vfs, path);
+        const merged = merge(parse(content));
+        const next = serialize(merged);
+        try {
+            await writeIndexWithRevision(vfs, path, next, revision);
+            // The read that produced the winning baseRevision is authoritative for
+            // existed-vs-new accounting: another writer cannot have raced us between
+            // this read and the matching CAS write without us seeing a conflict and
+            // looping.
+            return { existedAtWrite: content !== undefined };
+        }
+        catch (error) {
+            if (!isConflictError(error)) {
+                throw error;
+            }
+            lastError = error;
+            // Re-read on conflict; another writer beat us. Linear backoff prevents
+            // tight-looping a single hot index path while still resolving quickly.
+            if (attempt < maxAttempts - 1) {
+                await sleep(baseDelayMs * (attempt + 1));
+            }
+        }
+    }
+    throw new AtomicIndexExhaustedError(path, maxAttempts, lastError);
+}
+function defaultSleep(ms) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}
+//# sourceMappingURL=index.js.map

package/dist/src/atomic-index/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/atomic-index/index.ts"],"names":[],"mappings":"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"}

package/dist/src/index.d.ts

@@ -7,6 +7,8 @@ export * from "./ingest/openapi.js";
 export * from "./ingest/postman.js";
 export * from "./ingest/sample.js";
 export * from "./runtime/schema-adapter.js";
+export * from "./runtime/file-native-router.js";
+export * from "./runtime/writeback-status.js";
 export * from "./generate/adapter-generator.js";
 export * from "./generate/types-generator.js";
 export * from "./drift/drift-checker.js";
@@ -18,4 +20,5 @@ export * from "./docs/mapping-generator.js";
 export * from "./docs/change-detector.js";
 export * from "./docs/updater.js";
 export * from "./storage-bridge/index.js";
+export * from "./atomic-index/index.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/src/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAC;AAChC,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,iCAAiC,CAAC;AAChD,cAAc,+BAA+B,CAAC;AAC9C,cAAc,0BAA0B,CAAC;AACzC,cAAc,iBAAiB,CAAC;AAChC,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,mBAAmB,CAAC;AAClC,cAAc,2BAA2B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAC;AAChC,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,iCAAiC,CAAC;AAChD,cAAc,+BAA+B,CAAC;AAC9C,cAAc,iCAAiC,CAAC;AAChD,cAAc,+BAA+B,CAAC;AAC9C,cAAc,0BAA0B,CAAC;AACzC,cAAc,iBAAiB,CAAC;AAChC,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,mBAAmB,CAAC;AAClC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,yBAAyB,CAAC"}

package/dist/src/index.js

@@ -7,6 +7,8 @@ export * from "./ingest/openapi.js";
 export * from "./ingest/postman.js";
 export * from "./ingest/sample.js";
 export * from "./runtime/schema-adapter.js";
+export * from "./runtime/file-native-router.js";
+export * from "./runtime/writeback-status.js";
 export * from "./generate/adapter-generator.js";
 export * from "./generate/types-generator.js";
 export * from "./drift/drift-checker.js";
@@ -18,4 +20,5 @@ export * from "./docs/mapping-generator.js";
 export * from "./docs/change-detector.js";
 export * from "./docs/updater.js";
 export * from "./storage-bridge/index.js";
+export * from "./atomic-index/index.js";
 //# sourceMappingURL=index.js.map

package/dist/src/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAC;AAChC,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,iCAAiC,CAAC;AAChD,cAAc,+BAA+B,CAAC;AAC9C,cAAc,0BAA0B,CAAC;AACzC,cAAc,iBAAiB,CAAC;AAChC,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,mBAAmB,CAAC;AAClC,cAAc,2BAA2B,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAC;AAChC,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,iCAAiC,CAAC;AAChD,cAAc,+BAA+B,CAAC;AAC9C,cAAc,iCAAiC,CAAC;AAChD,cAAc,+BAA+B,CAAC;AAC9C,cAAc,0BAA0B,CAAC;AACzC,cAAc,iBAAiB,CAAC;AAChC,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,mBAAmB,CAAC;AAClC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,yBAAyB,CAAC"}

package/dist/src/runtime/file-native-router.d.ts

@@ -0,0 +1,98 @@
+import { type WritebackStatusEntry } from "./writeback-status.js";
+export type AdapterResourceOperation = "create" | "update" | "delete";
+export interface AdapterResourceConfig {
+    readonly name: string;
+    readonly path: string;
+    readonly pathPattern: RegExp;
+    readonly idPattern: RegExp;
+    readonly schema: string;
+    readonly createExample: string;
+    readonly operations?: readonly AdapterResourceOperation[];
+}
+export type FileNativeWritebackKind = "patch" | "create" | "delete";
+export type FileNativeWritebackEvent = "write" | "delete";
+export interface FileNativeWritebackRoute {
+    kind: FileNativeWritebackKind;
+    resource: AdapterResourceConfig;
+    id?: string;
+    canonical: boolean;
+}
+export interface FileNativeWritebackRequest {
+    readonly method?: string;
+    readonly endpoint?: string;
+    readonly action?: string;
+    readonly body?: unknown;
+    readonly [key: string]: unknown;
+}
+export interface FileNativeCreateReceipt {
+    readonly draftPath: string;
+    readonly canonicalPath?: string;
+    readonly id?: string;
+    readonly resource: string;
+    readonly createdAt: string;
+}
+export interface FileNativeWritebackExecutionOk {
+    readonly ok: true;
+    readonly route: FileNativeWritebackRoute;
+    readonly request?: FileNativeWritebackRequest;
+    readonly adapterResult?: unknown;
+    readonly createReceipt?: FileNativeCreateReceipt;
+    readonly status: WritebackStatusEntry;
+}
+export interface FileNativeWritebackExecutionFailed {
+    readonly ok: false;
+    readonly route?: FileNativeWritebackRoute;
+    readonly errors?: WritebackValidationError[];
+    readonly status?: WritebackStatusEntry;
+}
+export type FileNativeWritebackExecutionResult = FileNativeWritebackExecutionOk | FileNativeWritebackExecutionFailed;
+export interface ClassifyWriteOptions {
+    fsEvent?: FileNativeWritebackEvent;
+}
+export interface ExecuteFileNativeWritebackOptions {
+    path: string;
+    content?: string;
+    resources: readonly AdapterResourceConfig[];
+    fsEvent?: FileNativeWritebackEvent;
+    schemaRoot?: string;
+    loadSchema?: (resource: AdapterResourceConfig) => JsonSchema | Promise<JsonSchema>;
+    resolveWritebackRequest?: (path: string, content: string) => FileNativeWritebackRequest | Promise<FileNativeWritebackRequest>;
+    resolveDeleteRequest?: (path: string) => FileNativeWritebackRequest | Promise<FileNativeWritebackRequest>;
+    applyWriteback?: (request: FileNativeWritebackRequest, route: FileNativeWritebackRoute) => unknown | Promise<unknown>;
+    extractCreatedId?: (result: unknown, request: FileNativeWritebackRequest, route: FileNativeWritebackRoute) => string | undefined;
+    makeCanonicalPath?: (id: string, route: FileNativeWritebackRoute) => string | undefined;
+    recordStatus?: boolean;
+    now?: () => Date;
+}
+export interface JsonSchema {
+    readonly type?: string | readonly string[];
+    readonly required?: readonly string[];
+    readonly properties?: Readonly<Record<string, JsonSchema>>;
+    readonly additionalProperties?: boolean | JsonSchema;
+    readonly readOnly?: boolean;
+    readonly enum?: readonly unknown[];
+    readonly items?: JsonSchema;
+}
+export type WritebackValidationReason = "required" | "additionalProperties" | "readOnly" | "type" | "enum";
+export declare class ReadOnlyFieldError extends Error {
+    readonly field: string;
+    constructor(field: string);
+}
+export declare class WritebackValidationError extends Error {
+    readonly field?: string;
+    readonly reason: WritebackValidationReason;
+    constructor(input: {
+        field?: string;
+        reason: WritebackValidationReason;
+        message?: string;
+    });
+}
+export declare function classifyWrite(path: string, resources: readonly AdapterResourceConfig[], opts?: ClassifyWriteOptions): FileNativeWritebackRoute | null;
+export declare function validatePayload(payload: unknown, schema: JsonSchema, op: "patch" | "create"): {
+    ok: true;
+} | {
+    ok: false;
+    errors: WritebackValidationError[];
+};
+export declare function executeFileNativeWriteback(options: ExecuteFileNativeWritebackOptions): Promise<FileNativeWritebackExecutionResult>;
+//# sourceMappingURL=file-native-router.d.ts.map

package/dist/src/runtime/file-native-router.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-native-router.d.ts","sourceRoot":"","sources":["../../../src/runtime/file-native-router.ts"],"names":[],"mappings":"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"}