@omgbase/core 0.3.0 → 0.4.1

package/dist/src/sync/external-source.js

@@ -17,7 +17,7 @@ export async function createExternalSource(spec) {
     }
     const rl = createInterface({ input: child.stdout });
     let watchListener = null;
-    const router = messageRouter(rl, (paths) => watchListener?.(paths));
+    const router = messageRouter(rl, (ev) => watchListener?.(ev));
     const died = new Promise((_, reject) => {
         child.once("error", (err) => reject(new Error(`sync adapter '${spec.command}' failed to spawn: ${err.message}`)));
         child.once("exit", (code) => reject(new Error(`sync adapter '${spec.command}' exited early (code ${code ?? "?"})`)));
@@ -69,10 +69,19 @@ export async function createExternalSource(spec) {
         },
         ...(caps.watch
             ? {
-                async watch(onBatch) {
-                    watchListener = onBatch;
+                async watch(listener) {
+                    // `ready` resolves on the adapter's {"event":"ready"}; the listener sees
+                    // it as an event too, in wire order with the batches (spec/sync §5, §8).
+                    let markReady = () => { };
+                    const ready = new Promise((resolve) => { markReady = resolve; });
+                    watchListener = (ev) => {
+                        if (ev.event === "ready")
+                            markReady();
+                        listener(ev);
+                    };
                     await call("watch");
                     return {
+                        ready,
                         async stop() {
                             watchListener = null;
                             try {
@@ -105,9 +114,9 @@ export async function createExternalSource(spec) {
     };
     return source;
 }
-// Demultiplex adapter stdout: {"event":"batch"} lines feed the watch listener;
-// every other line is an id-addressed response buffered for nextResponse().
-function messageRouter(rl, onBatch) {
+// Demultiplex adapter stdout: {"event":…} lines feed the watch listener (ready,
+// batch); every other line is an id-addressed response buffered for nextResponse().
+function messageRouter(rl, onEvent) {
     const buffered = [];
     const waiters = [];
     rl.on("line", (line) => {
@@ -117,7 +126,11 @@ function messageRouter(rl, onBatch) {
         try {
             const peek = JSON.parse(trimmed);
             if (peek.event === "batch") {
-                onBatch(peek.paths ?? []);
+                onEvent({ event: "batch", paths: peek.paths ?? [] });
+                return;
+            }
+            if (peek.event === "ready") {
+                onEvent({ event: "ready" });
                 return;
             }
         }

package/dist/src/sync/plugin.d.ts

@@ -25,13 +25,38 @@ export interface SourceItem extends SourceEntry {
     /** The engine hashes this itself for the authoritative echo/convergence gate. */
     content: string;
 }
-/** A batch of changed storage-keys delivered by a live watch (13 §4.3). */
-export type WatchListener = (paths: string[]) => void;
+/**
+ * An unsolicited event of a live watch (spec/sync §5): `ready` once — the feed
+ * is primed and every change from now on will be reported — then `batch` lines
+ * of changed storage keys. An adapter built before sync 1.2 never sends `ready`.
+ */
+export type WatchEvent = {
+    event: "ready";
+} | {
+    event: "batch";
+    paths: string[];
+};
+/** Receives every event of a live watch, in wire order. */
+export type WatchListener = (event: WatchEvent) => void;
 /** A live subscription created by SyncSource.watch. */
 export interface SourceWatch {
-    /** Stop delivering batches and release resources. */
+    /**
+     * Resolves when the source reported `ready` (spec/sync §5). An in-process
+     * source resolves it at once; an adapter that never reports leaves it pending,
+     * so a host bounds the wait (`awaitReady`).
+     */
+    ready: Promise<void>;
+    /** Stop delivering events and release resources. */
     stop(): Promise<void>;
 }
+/** How long a host waits for `ready` before proceeding as if ready (spec/sync §5: unpinned; 30 s). */
+export declare const WATCH_READY_PATIENCE_MS = 30000;
+/**
+ * Wait for a watch's `ready` with bounded patience: `true` when it resolved in
+ * time, `false` on timeout (the host proceeds as if ready, with a warning — an
+ * adapter without `ready` still works, with the old window).
+ */
+export declare function awaitReady(ready: Promise<void>, patienceMs?: number): Promise<boolean>;
 /**
  * The in-engine handle to an external source process. Only capabilities/
  * enumerate/fetch are always meaningful; watch exists when capabilities().watch,
@@ -43,8 +68,8 @@ export interface SyncSource {
     enumerate(): Promise<SourceEntry[]>;
     /** Current state of one member, or null if it left the scope (a delete). */
     fetch(path: string): Promise<SourceItem | null>;
-    /** Subscribe to debounced change batches (push sources). */
-    watch?(onBatch: WatchListener): Promise<SourceWatch>;
+    /** Subscribe to the change feed (push sources): `ready` once, then debounced `batch` events. */
+    watch?(listener: WatchListener): Promise<SourceWatch>;
     /** Persist engine-authored bytes back to the source (writeThrough only). */
     write?(path: string, content: string): Promise<void>;
     /** Remove a member from the source (writeThrough only). */

package/dist/src/sync/plugin.js

@@ -8,5 +8,17 @@
 // reconciliation, commits, convergence, and durable revision/cursor state — so a
 // source only reports membership and transports bytes; it can never write a
 // commit, mint identity, or bypass the convergence check.
-export {};
+/** How long a host waits for `ready` before proceeding as if ready (spec/sync §5: unpinned; 30 s). */
+export const WATCH_READY_PATIENCE_MS = 30_000;
+/**
+ * Wait for a watch's `ready` with bounded patience: `true` when it resolved in
+ * time, `false` on timeout (the host proceeds as if ready, with a warning — an
+ * adapter without `ready` still works, with the old window).
+ */
+export function awaitReady(ready, patienceMs = WATCH_READY_PATIENCE_MS) {
+    return new Promise((resolve) => {
+        const timer = setTimeout(() => resolve(false), patienceMs);
+        ready.then(() => { clearTimeout(timer); resolve(true); }, () => { clearTimeout(timer); resolve(false); });
+    });
+}
 //# sourceMappingURL=plugin.js.map

package/dist/src/sync/watcher.d.ts

@@ -14,6 +14,8 @@ export declare class Watcher {
     private sub;
     constructor(store: Store, repoId: string, source: SyncSource, opts?: WatcherOptions);
     start(): Promise<void>;
+    /** The live subscription's `ready` (spec/sync §5); throws before `start()`. */
+    ready(): Promise<void>;
     private ingest;
     stop(): Promise<void>;
 }

package/dist/src/sync/watcher.js

@@ -14,11 +14,19 @@ export class Watcher {
     async start() {
         if (!this.source.watch)
             throw new Error("source does not support watch()");
-        this.sub = await this.source.watch((paths) => {
+        this.sub = await this.source.watch((ev) => {
+            if (ev.event !== "batch")
+                return; // `ready` is surfaced through ready()
             // A batch arrives from the adapter's stream; reconcile it off the callback.
-            void this.ingest(paths).catch((err) => this.opts.onError?.(err));
+            void this.ingest(ev.paths).catch((err) => this.opts.onError?.(err));
         });
     }
+    /** The live subscription's `ready` (spec/sync §5); throws before `start()`. */
+    ready() {
+        if (!this.sub)
+            throw new Error("watcher not started");
+        return this.sub.ready;
+    }
     async ingest(paths) {
         if (paths.length === 0)
             return null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@omgbase/core",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "Open Markdown Graph Base — embedded engine",
   "license": "MIT",
   "repository": {