@omgbase/sync 0.4.11 → 0.5.1

package/README.md

@@ -39,14 +39,14 @@ What it does, in order: spawn `--server` (split on whitespace) as a stdio MCP se
 
 All registered in `packages/core/src/mcp/server.ts`; every one takes an optional `repo` slug.
 
-- **`observe_many({files:[{path,content}]})`** → one result per file: `{docId, path, rev, commitId, converged, echo, conflicted, dispositions}`. Bytes are committed as an **observed**-origin revision (a write *around* the engine, as a human edit is recorded) with block identity threaded by the reconciler. If `sha256(content)` already equals the doc's stored `file_hash`, it is an **echo**: `echo:true`, `rev:null`, no commit. Bytes containing git conflict markers are still ingested and flagged `conflicted:true`. The batch shares one timestamp and one resurrection-pool sweep. (`observe` is the single-file form; the coordinator uses the batch.)
-- **`observe_delete({path})`** → `{docId, path, deleted}`. Tombstones the live doc as an observed deletion (blocks pooled for resurrection, no file removed). Idempotent.
-- **`changes_since({cursor?, origin?, limit?})`** → `{digests, cursor, truncated, head}`. The repo-wide commit feed after a commit `seq`; each digest is `{commit, seq, ts, origin, actor, summary, revisions:[{doc, path, contentHash}]}` where `contentHash` is the hex of that revision's rendered file hash — enough for a client to tell "changed vs echo" without a follow-up read. `head` is the repo's current max seq (cursor > head means the cursor came from another repo).
+- **`observe_many({files:[{path,content}]})`** → one result per file: `{id, path, rev, commitId, converged, echo, conflicted, dispositions}` (surface 3.0; `docId`/`path` before). Bytes are committed as an **observed**-origin revision (a write *around* the engine, as a human edit is recorded) with block identity threaded by the reconciler. If `sha256(content)` already equals the doc's stored `file_hash`, it is an **echo**: `echo:true`, `rev:null`, no commit. Bytes containing git conflict markers are still ingested and flagged `conflicted:true`. The batch shares one timestamp and one resurrection-pool sweep. (`observe` is the single-file form; the coordinator uses the batch.)
+- **`observe_delete({path})`** → `{id, path, deleted}`. Tombstones the live doc as an observed deletion (blocks pooled for resurrection, no file removed). Idempotent.
+- **`changes_since({cursor?, origin?, limit?})`** → `{digests, cursor, truncated, head}`. The repo-wide commit feed after a commit `seq`; each digest is `{commit, seq, ts, origin, actor, summary, revisions:[{id, path, hash}]}` (sync 2.0; `{doc, path, contentHash}` before) where `hash` is the hex of that revision's rendered file hash — enough for a client to tell "changed vs echo" without a follow-up read. `head` is the repo's current max seq (cursor > head means the cursor came from another repo).
 - **`docs_read({path})`** — used by `readDoc()` in the export direction to get a doc's current byte-exact content.
 
 ### Loop safety and echo suppression
 
-A round-trip source → engine → source → engine terminates because the engine's echo gate makes ingest idempotent: re-observing bytes the engine already holds produces no commit. `syncOut()` adds a coarse filter on top — it **skips every `observed`-origin digest**, since those came from a source and there is nothing to push back — leaving only `api`/`import` (engine-authored) changes to write out. The `contentHash` in the feed and in `readDoc()` is carried for finer per-path suppression but the v1 coordinator does not yet compare it; the durable per-path hash store (`sync_state`) is the deferred piece below.
+A round-trip source → engine → source → engine terminates because the engine's echo gate makes ingest idempotent: re-observing bytes the engine already holds produces no commit. `syncOut()` adds a coarse filter on top — it **skips every `observed`-origin digest**, since those came from a source and there is nothing to push back — leaving only `api`/`import` (engine-authored) changes to write out. The `hash` in the feed (and `contentHash` in `readDoc()`'s own `EngineClient` type) is carried for finer per-path suppression but the v1 coordinator does not yet compare it; the durable per-path hash store (`sync_state`) is the deferred piece below.
 
 ## The identity rule
 

package/dist/src/coordinator.js

@@ -65,7 +65,8 @@ export class Coordinator {
                 if (digest.origin === "observed")
                     continue; // came from a source; don't echo back
                 for (const rev of digest.revisions) {
-                    // `changes_since` reports the reference form; the source takes storage paths.
+                    // `changes_since` reports the reference form (`path`, spec/surface
+                    // §1.2); the source takes storage paths.
                     const path = storagePath(rev.path);
                     const doc = await this.engine.readDoc(path);
                     if (doc) {

package/dist/src/engine-client.d.ts

@@ -8,7 +8,7 @@ export interface ChangesPage {
 }
 export interface DocBytes {
     content: string;
-    /** hex of the doc's current rendered/file hash (matches changes_since contentHash). */
+    /** hex of the doc's current rendered/file hash (matches a changes_since revision's `hash`). */
     contentHash: string;
 }
 export interface EngineClient {

package/dist/src/engine-client.js

@@ -30,7 +30,7 @@ export class InProcessEngineClient {
         const res = docsRead(this.store, row.doc_id);
         if (!res)
             return Promise.resolve(null);
-        return Promise.resolve({ content: res.content, contentHash: row.file_hash?.toString("hex") ?? "" });
+        return Promise.resolve({ content: res.raw, contentHash: row.file_hash?.toString("hex") ?? "" });
     }
     close() {
         // The store's lifetime is owned by the caller (it may serve other work).

package/dist/src/mcp-engine-client.js

@@ -28,11 +28,15 @@ export class McpEngineClient {
         }
         return body;
     }
-    observeMany(files) {
-        return this.callTool("observe_many", { files });
+    // The wire spells a document's identity `id`/`path` (spec/surface §1.2,
+    // 3.0); the engine-client contract keeps the library's `docId`/`path`
+    // (spec/store's observe outcome), so the two are mapped back here.
+    async observeMany(files) {
+        const out = await this.callTool("observe_many", { files });
+        return out.map(fromWireObserve);
     }
-    observeDelete(path) {
-        return this.callTool("observe_delete", { path });
+    async observeDelete(path) {
+        return fromWireObserve(await this.callTool("observe_delete", { path }));
     }
     changesSince(cursor, opts) {
         return this.callTool("changes_since", {
@@ -44,7 +48,7 @@ export class McpEngineClient {
     async readDoc(path) {
         try {
             const res = await this.callTool("docs_read", { path });
-            return { content: res.content, contentHash: createHash("sha256").update(res.content, "utf8").digest("hex") };
+            return { content: res.raw, contentHash: createHash("sha256").update(res.raw, "utf8").digest("hex") };
         }
         catch {
             // doc_missing (or any read failure) → treat as absent.
@@ -55,6 +59,11 @@ export class McpEngineClient {
         await this.client.close();
     }
 }
+/** A wire observe outcome (`{ id, path, … }`) as the library's `{ docId, path, … }`. */
+function fromWireObserve(w) {
+    const { id, path, ...rest } = w;
+    return { docId: id, path: path, ...rest };
+}
 /** Connect to an omgbase MCP server over stdio by spawning `command args`
  *  (e.g. `omg mcp -C /vault`). Returns a ready EngineClient. */
 export async function connectStdioEngine(spec) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@omgbase/sync",
-  "version": "0.4.11",
+  "version": "0.5.1",
   "description": "Open Markdown Graph Base — standalone store-to-store synchronizer: a coordinator over an EngineClient seam (in-process or MCP-client) and source adapters",
   "license": "MIT",
   "repository": {
@@ -53,7 +53,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.30.0",
-    "@omgbase/core": "^0.10.1",
+    "@omgbase/core": "^0.11.1",
     "@omgbase/fs-adapter": "^0.2.0"
   },
   "scripts": {