sh3-core 0.8.2 → 0.9.1

package/dist/app/store/storeShard.svelte.js

@@ -16,7 +16,9 @@ import StoreView from './StoreView.svelte';
 import InstalledView from './InstalledView.svelte';
 import { fetchRegistries, fetchBundle, fetchServerBundle, buildPackageMeta } from '../../registry/client';
 import { installPackage, listInstalledPackages } from '../../registry/installer';
-import { loadBundle, savePackage } from '../../registry/storage';
+import { loadBundle, loadMeta, savePackage } from '../../registry/storage';
+import { loadBundleModule } from '../../registry/loader';
+import { extractBundlePermissions } from '../../registry/permission-descriptions';
 import { serverInstallPackage, fetchServerPackages } from '../../env/client';
 import { VERSION } from '../../version';
 import { installVerb, uninstallVerb, appinfoVerb } from './verbs';
@@ -41,6 +43,19 @@ function isNewerVersion(available, installed) {
     }
     return false;
 }
+/**
+ * Compute added and removed permissions between two manifest snapshots.
+ * Order within each array follows the input order of `newPerms` (for added)
+ * and `oldPerms` (for removed). No duplicates — both inputs assumed unique.
+ */
+export function diffPermissions(oldPerms, newPerms) {
+    const oldSet = new Set(oldPerms);
+    const newSet = new Set(newPerms);
+    return {
+        added: newPerms.filter((p) => !oldSet.has(p)),
+        removed: oldPerms.filter((p) => !newSet.has(p)),
+    };
+}
 /**
  * Module-level context set during activate(). Imported by the Svelte
  * view components so they can read/write store state and trigger refreshes.
@@ -105,6 +120,7 @@ export const storeShard = {
                         sourceRegistry: (_a = p.sourceRegistry) !== null && _a !== void 0 ? _a : '',
                         contractVersion: (_b = p.contractVersion) !== null && _b !== void 0 ? _b : '',
                         installedAt: (_c = p.installedAt) !== null && _c !== void 0 ? _c : '',
+                        permissions: [],
                     });
                 });
                 recomputeUpdatable();
@@ -133,7 +149,7 @@ export const storeShard = {
             const registries = env.registries.filter((r) => r !== url);
             await ctx.envUpdate({ registries });
         }
-        async function updatePackage(id) {
+        async function updatePackage(id, confirmPermissionChange) {
             var _a, _b, _c, _d;
             const catalogEntry = state.ephemeral.updatable[id];
             if (!catalogEntry)
@@ -148,10 +164,37 @@ export const storeShard = {
                 serverBundle = await fetchServerBundle(catalogEntry.latest, catalogEntry.sourceRegistry);
             }
             const meta = buildPackageMeta(catalogEntry, catalogEntry.latest);
-            // 2. Snapshot current state for rollback.
+            // 2. Load the module once for permission extraction and install reuse.
+            const loaded = await loadBundleModule(bundle);
+            const newPerms = extractBundlePermissions(loaded);
+            // 3. Look up the locally persisted old permissions (server-sourced
+            //    installed list doesn't carry permissions — per spec they live
+            //    in the local IndexedDB record).
+            let oldPerms = [];
+            try {
+                const localMeta = await loadMeta(id);
+                if (localMeta === null || localMeta === void 0 ? void 0 : localMeta.permissions)
+                    oldPerms = localMeta.permissions;
+            }
+            catch (_e) {
+                // No local record (e.g. installed on a different browser); treat as
+                // empty. The diff will show all new permissions as additions.
+            }
+            // 4. If the permission set changed and a confirmation callback was
+            //    provided, await the user's decision before touching the server.
+            const { added, removed } = diffPermissions(oldPerms, newPerms);
+            if ((added.length > 0 || removed.length > 0) && confirmPermissionChange) {
+                const ok = await confirmPermissionChange(added, removed);
+                if (!ok)
+                    return;
+            }
+            // 5. Snapshot current state for rollback. Preserve the locally-known
+            //    permissions so the rollback write still satisfies the InstalledPackage
+            //    contract (installedRecord came from the server-sourced list which
+            //    lacks permissions).
             const oldBundle = await loadBundle(id);
-            const oldRecord = Object.assign({}, installedRecord);
-            // 3. Push to server.
+            const oldRecord = Object.assign(Object.assign({}, installedRecord), { permissions: oldPerms });
+            // 6. Push to server.
             const manifest = {
                 id: meta.id,
                 type: meta.type,
@@ -171,8 +214,9 @@ export const storeShard = {
                 }
                 throw new Error(message);
             }
-            // 4. Install locally (overwrites IndexedDB + re-registers).
-            const result = await installPackage(bundle, meta);
+            // 7. Install locally (overwrites IndexedDB + re-registers). Reuse the
+            //    already-loaded bundle so the ESM is not evaluated twice.
+            const result = await installPackage(bundle, meta, { loaded });
             if (!result.success) {
                 // Rollback: restore old bundle and metadata.
                 if (oldBundle) {

package/dist/app/store/storeShard.svelte.test.js

@@ -0,0 +1,34 @@
+import { describe, it, expect } from 'vitest';
+import { diffPermissions } from './storeShard.svelte';
+describe('diffPermissions', () => {
+    it('returns empty added and removed when the sets are identical', () => {
+        expect(diffPermissions(['a', 'b'], ['a', 'b'])).toEqual({
+            added: [],
+            removed: [],
+        });
+    });
+    it('detects permissions added by the new version', () => {
+        expect(diffPermissions(['a'], ['a', 'b'])).toEqual({
+            added: ['b'],
+            removed: [],
+        });
+    });
+    it('detects permissions removed by the new version', () => {
+        expect(diffPermissions(['a', 'b'], ['a'])).toEqual({
+            added: [],
+            removed: ['b'],
+        });
+    });
+    it('reports both added and removed when the set changes in both directions', () => {
+        expect(diffPermissions(['a', 'b'], ['b', 'c'])).toEqual({
+            added: ['c'],
+            removed: ['a'],
+        });
+    });
+    it('treats an empty old set as "everything is new"', () => {
+        expect(diffPermissions([], ['a', 'b'])).toEqual({
+            added: ['a', 'b'],
+            removed: [],
+        });
+    });
+});

package/dist/apps/types.d.ts

@@ -41,7 +41,9 @@ export interface AppManifest {
      * Declared in the manifest and surfaced to the user at install time
      * by the store app. Currently recognized:
      *   - 'state:manage' — cross-shard zone access.
-     *   - 'documents:sync' — cross-shard document sync API.
+     *
+     * Sync-related permissions (`sync:policy`, `sync:peer`) are introduced
+     * in a later plan alongside the server-side sync runtime.
      */
     permissions?: string[];
 }
@@ -62,10 +64,6 @@ export interface AppContext {
      * Cross-shard zone management API. Only present when the app's
      * manifest declares the `'state:manage'` permission. Check with
      * `if (ctx.zones)` before use.
-     *
-     * Related permissions also recognized by the framework:
-     *   - 'documents:sync' — cross-shard document sync API (exposed on
-     *     shard contexts as `ctx.sync()`, not on app contexts).
      */
     zones?: ZoneManager;
 }

package/dist/documents/backends.d.ts

@@ -1,4 +1,5 @@
 import type { DocumentBackend, DocumentMeta } from './types';
+import type { DocStatus } from './sync-types';
 export declare class MemoryDocumentBackend implements DocumentBackend {
     #private;
     read(tenantId: string, shardId: string, path: string): Promise<string | ArrayBuffer | null>;
@@ -10,6 +11,7 @@ export declare class MemoryDocumentBackend implements DocumentBackend {
     listAllDocuments(tenantId: string): Promise<Array<DocumentMeta & {
         shardId: string;
     }>>;
+    readMeta(tenantId: string, shardId: string, path: string): Promise<DocStatus | null>;
 }
 export declare class IndexedDBDocumentBackend implements DocumentBackend {
     #private;

package/dist/documents/backends.js

@@ -92,6 +92,12 @@ export class MemoryDocumentBackend {
         }
         return out;
     }
+    async readMeta(tenantId, shardId, path) {
+        const entry = __classPrivateFieldGet(this, _MemoryDocumentBackend_store, "f").get(compositeKey(tenantId, shardId, path));
+        if (!entry)
+            return null;
+        return { exists: true, version: 1, syncMode: 'sync', syncState: 'synced' };
+    }
 }
 _MemoryDocumentBackend_store = new WeakMap();
 // ---------------------------------------------------------------------------

package/dist/documents/browse.d.ts

@@ -8,5 +8,35 @@ export interface BrowseCapability {
     watchDocuments(callback: (change: DocumentChange) => void): () => void;
     /** Enumerate shard ids with at least one document in the tenant. */
     listShards(): Promise<string[]>;
+    /**
+     * Read content from any shard's document namespace within the active
+     * tenant. Available only when the caller declares both
+     * `documents:browse` and `documents:read`. Returns the content string
+     * (text-format docs), ArrayBuffer (binary-format docs), or null if the
+     * document does not exist. Tenant-scoped — cannot cross tenants.
+     *
+     * Absent (undefined) on the capability object when `documents:read`
+     * is not declared; feature-detect with
+     * `typeof ctx.browse.readFrom === 'function'`.
+     */
+    readFrom?(shardId: string, path: string): Promise<string | ArrayBuffer | null>;
+    /**
+     * Write content into any shard's document namespace within the active
+     * tenant. Available only when the caller declares both
+     * `documents:browse` and `documents:write`. Emits a normal
+     * `DocumentChange` so other shards and the file-explorer pick up the
+     * new or updated document. Tenant-scoped — cannot cross tenants.
+     *
+     * Absent (undefined) on the capability object when `documents:write`
+     * is not declared; feature-detect with
+     * `typeof ctx.browse.writeTo === 'function'`.
+     */
+    writeTo?(shardId: string, path: string, content: string | ArrayBuffer): Promise<void>;
 }
-export declare function createBrowseCapability(tenantId: string, backend: DocumentBackend): BrowseCapability;
+export interface BrowseCapabilityOptions {
+    /** When true, the returned capability exposes `readFrom`. */
+    canRead: boolean;
+    /** When true, the returned capability exposes `writeTo`. */
+    canWrite: boolean;
+}
+export declare function createBrowseCapability(tenantId: string, backend: DocumentBackend, options?: BrowseCapabilityOptions): BrowseCapability;

package/dist/documents/browse.js

@@ -6,8 +6,8 @@
  * the owning shard's own ctx.documents() handle.
  */
 import { documentChanges } from './notifications';
-export function createBrowseCapability(tenantId, backend) {
-    return {
+export function createBrowseCapability(tenantId, backend, options = { canRead: false, canWrite: false }) {
+    const capability = {
         listDocuments: () => backend.listAllDocuments(tenantId),
         listShards: () => backend.listAllShards(tenantId),
         watchDocuments: (callback) => documentChanges.subscribe((change) => {
@@ -16,4 +16,20 @@ export function createBrowseCapability(tenantId, backend) {
             callback(change);
         }),
     };
+    if (options.canRead) {
+        capability.readFrom = (shardId, path) => backend.read(tenantId, shardId, path);
+    }
+    if (options.canWrite) {
+        capability.writeTo = async (shardId, path, content) => {
+            const existed = await backend.exists(tenantId, shardId, path);
+            await backend.write(tenantId, shardId, path, content);
+            documentChanges.emit({
+                type: existed ? 'update' : 'create',
+                path,
+                tenantId,
+                shardId,
+            });
+        };
+    }
+    return capability;
 }

package/dist/documents/browse.test.js

@@ -38,4 +38,85 @@ describe('BrowseCapability', () => {
         documentChanges.emit({ type: 'create', path: 'f.txt', tenantId: 't1', shardId: 's1' });
         expect(cb).not.toHaveBeenCalled();
     });
+    describe('readFrom (documents:read gate)', () => {
+        it('is absent when canRead is false', () => {
+            const be = new MemoryDocumentBackend();
+            const browse = createBrowseCapability('t1', be, { canRead: false, canWrite: false });
+            expect(browse.readFrom).toBeUndefined();
+        });
+        it('is present when canRead is true', () => {
+            const be = new MemoryDocumentBackend();
+            const browse = createBrowseCapability('t1', be, { canRead: true, canWrite: false });
+            expect(typeof browse.readFrom).toBe('function');
+        });
+        it('reads content from a foreign shard namespace', async () => {
+            const be = new MemoryDocumentBackend();
+            await be.write('t1', 'other', 'notes/ideas.md', 'hello');
+            const browse = createBrowseCapability('t1', be, { canRead: true, canWrite: false });
+            expect(await browse.readFrom('other', 'notes/ideas.md')).toBe('hello');
+        });
+        it('returns null when the foreign document does not exist', async () => {
+            const be = new MemoryDocumentBackend();
+            const browse = createBrowseCapability('t1', be, { canRead: true, canWrite: false });
+            expect(await browse.readFrom('other', 'nope.txt')).toBeNull();
+        });
+        it('never crosses tenants: a t1 capability cannot read t2 docs', async () => {
+            const be = new MemoryDocumentBackend();
+            await be.write('t2', 's', 'secret.txt', 'hidden');
+            const browse = createBrowseCapability('t1', be, { canRead: true, canWrite: false });
+            expect(await browse.readFrom('s', 'secret.txt')).toBeNull();
+        });
+    });
+    describe('writeTo (documents:write gate)', () => {
+        it('is absent when canWrite is false', () => {
+            const be = new MemoryDocumentBackend();
+            const browse = createBrowseCapability('t1', be, { canRead: false, canWrite: false });
+            expect(browse.writeTo).toBeUndefined();
+        });
+        it('is present when canWrite is true', () => {
+            const be = new MemoryDocumentBackend();
+            const browse = createBrowseCapability('t1', be, { canRead: false, canWrite: true });
+            expect(typeof browse.writeTo).toBe('function');
+        });
+        it('writes into the target shard namespace and emits a create change', async () => {
+            const be = new MemoryDocumentBackend();
+            const browse = createBrowseCapability('t1', be, { canRead: false, canWrite: true });
+            const events = [];
+            const unsub = documentChanges.subscribe((c) => events.push(c));
+            await browse.writeTo('target-shard', 'notes/ideas.md', 'hello');
+            expect(await be.read('t1', 'target-shard', 'notes/ideas.md')).toBe('hello');
+            expect(events).toEqual([
+                { type: 'create', path: 'notes/ideas.md', tenantId: 't1', shardId: 'target-shard' },
+            ]);
+            unsub();
+        });
+        it('emits update (not create) when overwriting an existing document', async () => {
+            const be = new MemoryDocumentBackend();
+            await be.write('t1', 'target-shard', 'a.txt', 'v1');
+            const browse = createBrowseCapability('t1', be, { canRead: false, canWrite: true });
+            const events = [];
+            const unsub = documentChanges.subscribe((c) => events.push(c));
+            await browse.writeTo('target-shard', 'a.txt', 'v2');
+            expect(await be.read('t1', 'target-shard', 'a.txt')).toBe('v2');
+            expect(events).toEqual([
+                { type: 'update', path: 'a.txt', tenantId: 't1', shardId: 'target-shard' },
+            ]);
+            unsub();
+        });
+        it('never crosses tenants: cannot be tricked into writing into tenant b', async () => {
+            const be = new MemoryDocumentBackend();
+            const browse = createBrowseCapability('t1', be, { canRead: false, canWrite: true });
+            await browse.writeTo('s', 'a.txt', 'x');
+            expect(await be.read('t1', 's', 'a.txt')).toBe('x');
+            expect(await be.read('t2', 's', 'a.txt')).toBeNull();
+        });
+    });
+    describe('read + write combined', () => {
+        it('round-trips content through readFrom after writeTo', async () => {
+            const be = new MemoryDocumentBackend();
+            const browse = createBrowseCapability('t1', be, { canRead: true, canWrite: true });
+            await browse.writeTo('shard-x', 'doc.txt', 'roundtrip');
+            expect(await browse.readFrom('shard-x', 'doc.txt')).toBe('roundtrip');
+        });
+    });
 });

package/dist/documents/handle.js

@@ -18,8 +18,6 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
 };
 var _AutosaveControllerImpl_instances, _AutosaveControllerImpl_handle, _AutosaveControllerImpl_path, _AutosaveControllerImpl_debounceMs, _AutosaveControllerImpl_pending, _AutosaveControllerImpl_timer, _AutosaveControllerImpl_dirty, _AutosaveControllerImpl_disposed, _AutosaveControllerImpl_scheduleFlush, _AutosaveControllerImpl_clearTimer;
 import { documentChanges } from './notifications';
-import { notifyJournal } from './journal-hook';
-import { hashContent } from './sync/hash';
 const DEFAULT_DEBOUNCE_MS = 1000;
 /**
  * Create a document handle scoped to a tenant, shard, and file filter.
@@ -55,17 +53,27 @@ export function createDocumentHandle(tenantId, shardId, backend, options) {
             const existed = await backend.exists(tenantId, shardId, path);
             await backend.write(tenantId, shardId, path, content);
             emitChange(existed ? 'update' : 'create', path);
-            const hash = await hashContent(content);
-            await notifyJournal({ shardId, path, op: 'upsert', hash });
         },
         async delete(path) {
             await backend.delete(tenantId, shardId, path);
             emitChange('delete', path);
-            await notifyJournal({ shardId, path, op: 'delete', hash: null });
         },
         async exists(path) {
             return backend.exists(tenantId, shardId, path);
         },
+        async status(path) {
+            if (!backend.readMeta)
+                throw new Error('Backend does not support status()');
+            return backend.readMeta(tenantId, shardId, path);
+        },
+        async resolveConflict(path, choice) {
+            if (!backend.resolve)
+                throw new Error('Backend does not support resolveConflict()');
+            if (typeof choice !== 'string' && !(typeof choice === 'object' && 'origin' in choice)) {
+                throw new Error('choice must be a string or { origin } object');
+            }
+            return backend.resolve(tenantId, shardId, path, choice);
+        },
         watch(callback) {
             // Subscribe to global emitter, filtered to this handle's scope.
             const unsub = documentChanges.subscribe((change) => {

package/dist/documents/handle.test.js

@@ -0,0 +1,55 @@
+import { describe, it, expect } from 'vitest';
+import { MemoryDocumentBackend } from './backends';
+import { createDocumentHandle } from './handle';
+function harness() {
+    const backend = new MemoryDocumentBackend();
+    const handle = createDocumentHandle('tenant1', 'shard1', backend, { format: 'text' });
+    return { backend, handle };
+}
+describe('DocumentHandle.status()', () => {
+    it('returns null for a missing doc', async () => {
+        const { handle } = harness();
+        expect(await handle.status('nope.txt')).toBeNull();
+    });
+    it('returns DocStatus after a write', async () => {
+        const { handle } = harness();
+        await handle.write('a.txt', 'hi');
+        const s = await handle.status('a.txt');
+        expect(s).toMatchObject({ exists: true, version: 1, syncState: 'synced' });
+    });
+    it('throws if the backend does not implement readMeta', async () => {
+        const backend = {
+            async read() { return null; },
+            async write() { },
+            async delete() { },
+            async list() { return []; },
+            async exists() { return false; },
+            async listAllShards() { return []; },
+            async listAllDocuments() { return []; },
+        };
+        const handle = createDocumentHandle('t', 's', backend, { format: 'text' });
+        await expect(handle.status('a.txt')).rejects.toThrow(/status/);
+    });
+});
+describe('DocumentHandle.resolveConflict()', () => {
+    it('delegates to backend.resolve with the chosen origin', async () => {
+        const resolved = [];
+        const backend = {
+            async read() { return null; },
+            async write() { },
+            async delete() { },
+            async list() { return []; },
+            async exists() { return false; },
+            async listAllShards() { return []; },
+            async listAllDocuments() { return []; },
+            async resolve(t, s, p, c) { resolved.push({ t, s, p, c }); },
+        };
+        const handle = createDocumentHandle('tenant1', 'shard1', backend, { format: 'text' });
+        await handle.resolveConflict('a.txt', 'local');
+        expect(resolved).toEqual([{ t: 'tenant1', s: 'shard1', p: 'a.txt', c: 'local' }]);
+    });
+    it('throws if the backend does not implement resolve', async () => {
+        const { handle } = harness();
+        await expect(handle.resolveConflict('a.txt', 'local')).rejects.toThrow(/resolveConflict/);
+    });
+});

package/dist/documents/http-backend.d.ts

@@ -1,12 +1,15 @@
 /**
  * HTTP document backend — connects to sh3-server's document API.
  *
- * Implements the DocumentBackend interface over HTTP. Read operations
- * are unauthenticated; write operations send the API key as a Bearer
- * token. This is the web-hosted equivalent of the Tauri filesystem
- * backend.
+ * Implements the DocumentBackend interface over HTTP. Every request
+ * includes credentials (session cookie) so a logged-in user's tenant
+ * identity reaches sh3-server; write operations additionally send the
+ * API key as a Bearer token. This is the web-hosted equivalent of the
+ * Tauri filesystem backend. Server open-mode (auth.required=false)
+ * bypasses tenant checks regardless.
  */
 import type { DocumentBackend, DocumentMeta } from './types';
+import type { DocStatus } from './sync-types';
 export declare class HttpDocumentBackend implements DocumentBackend {
     #private;
     /**
@@ -23,4 +26,8 @@ export declare class HttpDocumentBackend implements DocumentBackend {
     listAllDocuments(tenantId: string): Promise<Array<DocumentMeta & {
         shardId: string;
     }>>;
+    readMeta(tenantId: string, shardId: string, path: string): Promise<DocStatus | null>;
+    resolve(tenantId: string, shardId: string, path: string, choice: 'local' | 'remote' | {
+        origin: string;
+    } | string): Promise<void>;
 }

package/dist/documents/http-backend.js

@@ -1,10 +1,12 @@
 /**
  * HTTP document backend — connects to sh3-server's document API.
  *
- * Implements the DocumentBackend interface over HTTP. Read operations
- * are unauthenticated; write operations send the API key as a Bearer
- * token. This is the web-hosted equivalent of the Tauri filesystem
- * backend.
+ * Implements the DocumentBackend interface over HTTP. Every request
+ * includes credentials (session cookie) so a logged-in user's tenant
+ * identity reaches sh3-server; write operations additionally send the
+ * API key as a Bearer token. This is the web-hosted equivalent of the
+ * Tauri filesystem backend. Server open-mode (auth.required=false)
+ * bypasses tenant checks regardless.
  */
 var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
     if (kind === "m") throw new TypeError("Private method is not writable");
@@ -34,7 +36,7 @@ export class HttpDocumentBackend {
     async read(tenantId, shardId, path) {
         var _a;
         const url = `${__classPrivateFieldGet(this, _HttpDocumentBackend_baseUrl, "f")}/api/docs/${tenantId}/${shardId}/${path}`;
-        const res = await fetch(url);
+        const res = await fetch(url, { credentials: 'include' });
         if (res.status === 404)
             return null;
         if (!res.ok)
@@ -48,42 +50,66 @@ export class HttpDocumentBackend {
     async write(tenantId, shardId, path, content) {
         const url = `${__classPrivateFieldGet(this, _HttpDocumentBackend_baseUrl, "f")}/api/docs/${tenantId}/${shardId}/${path}`;
         const headers = Object.assign(Object.assign({}, __classPrivateFieldGet(this, _HttpDocumentBackend_instances, "m", _HttpDocumentBackend_authHeaders).call(this)), { 'Content-Type': typeof content === 'string' ? 'text/plain' : 'application/octet-stream' });
-        const res = await fetch(url, { method: 'PUT', headers, body: content });
+        const res = await fetch(url, { method: 'PUT', headers, body: content, credentials: 'include' });
         if (!res.ok)
             throw new Error(`Document write failed: ${res.status}`);
     }
     async delete(tenantId, shardId, path) {
         const url = `${__classPrivateFieldGet(this, _HttpDocumentBackend_baseUrl, "f")}/api/docs/${tenantId}/${shardId}/${path}`;
-        const res = await fetch(url, { method: 'DELETE', headers: __classPrivateFieldGet(this, _HttpDocumentBackend_instances, "m", _HttpDocumentBackend_authHeaders).call(this) });
+        const res = await fetch(url, { method: 'DELETE', headers: __classPrivateFieldGet(this, _HttpDocumentBackend_instances, "m", _HttpDocumentBackend_authHeaders).call(this), credentials: 'include' });
         if (!res.ok)
             throw new Error(`Document delete failed: ${res.status}`);
     }
     async list(tenantId, shardId) {
         const url = `${__classPrivateFieldGet(this, _HttpDocumentBackend_baseUrl, "f")}/api/docs/${tenantId}/${shardId}`;
-        const res = await fetch(url);
+        const res = await fetch(url, { credentials: 'include' });
         if (!res.ok)
             throw new Error(`Document list failed: ${res.status}`);
         return res.json();
     }
     async exists(tenantId, shardId, path) {
         const url = `${__classPrivateFieldGet(this, _HttpDocumentBackend_baseUrl, "f")}/api/docs/${tenantId}/${shardId}/${path}`;
-        const res = await fetch(url, { method: 'HEAD' });
+        const res = await fetch(url, { method: 'HEAD', credentials: 'include' });
         return res.ok;
     }
     async listAllShards(tenantId) {
         const url = `${__classPrivateFieldGet(this, _HttpDocumentBackend_baseUrl, "f")}/api/docs/${tenantId}/_shards`;
-        const res = await fetch(url);
+        const res = await fetch(url, { credentials: 'include' });
         if (!res.ok)
             throw new Error(`listAllShards failed: ${res.status}`);
         return res.json();
     }
     async listAllDocuments(tenantId) {
         const url = `${__classPrivateFieldGet(this, _HttpDocumentBackend_baseUrl, "f")}/api/docs/${tenantId}/_all`;
-        const res = await fetch(url);
+        const res = await fetch(url, { credentials: 'include' });
         if (!res.ok)
             throw new Error(`listAllDocuments failed: ${res.status}`);
         return res.json();
     }
+    async readMeta(tenantId, shardId, path) {
+        const url = `${__classPrivateFieldGet(this, _HttpDocumentBackend_baseUrl, "f")}/api/docs/${tenantId}/${shardId}/${path}?meta=1`;
+        const res = await fetch(url, { credentials: 'include' });
+        if (!res.ok)
+            throw new Error(`readMeta failed: ${res.status}`);
+        const body = await res.json();
+        if (!body.exists)
+            return null;
+        return body;
+    }
+    async resolve(tenantId, shardId, path, choice) {
+        const url = `${__classPrivateFieldGet(this, _HttpDocumentBackend_baseUrl, "f")}/api/docs/${tenantId}/${shardId}/${path}/resolve`;
+        const body = typeof choice === 'string'
+            ? { choice }
+            : { choice: choice.origin };
+        const res = await fetch(url, {
+            method: 'POST',
+            credentials: 'include',
+            headers: Object.assign(Object.assign({}, __classPrivateFieldGet(this, _HttpDocumentBackend_instances, "m", _HttpDocumentBackend_authHeaders).call(this)), { 'Content-Type': 'application/json' }),
+            body: JSON.stringify(body),
+        });
+        if (!res.ok)
+            throw new Error(`resolve failed: ${res.status}`);
+    }
 }
 _HttpDocumentBackend_baseUrl = new WeakMap(), _HttpDocumentBackend_apiKey = new WeakMap(), _HttpDocumentBackend_instances = new WeakSet(), _HttpDocumentBackend_authHeaders = function _HttpDocumentBackend_authHeaders() {
     if (!__classPrivateFieldGet(this, _HttpDocumentBackend_apiKey, "f"))

package/dist/documents/index.d.ts

@@ -4,4 +4,5 @@ export { HttpDocumentBackend } from './http-backend';
 export { createDocumentHandle } from './handle';
 export { documentChanges } from './notifications';
 export { getTenantId, getDocumentBackend, __setTenantId, __setDocumentBackend, } from './config';
-export * from './sync';
+export type { SyncPolicy, SyncPolicyRule, DocStatus, ConflictFile, ConflictBranch, } from './sync-types';
+export { PERMISSION_SYNC_PEER, PERMISSION_SYNC_POLICY, } from './sync-types';

package/dist/documents/index.js

@@ -6,4 +6,4 @@ export { HttpDocumentBackend } from './http-backend';
 export { createDocumentHandle } from './handle';
 export { documentChanges } from './notifications';
 export { getTenantId, getDocumentBackend, __setTenantId, __setDocumentBackend, } from './config';
-export * from './sync';
+export { PERMISSION_SYNC_PEER, PERMISSION_SYNC_POLICY, } from './sync-types';

package/dist/documents/sync-types.d.ts

@@ -0,0 +1,45 @@
+/** Server-side sync policy (ADR-019 §9). Lives at {tenant}/__sync__/policy.json. */
+export interface SyncPolicy {
+    /** Schema version. Increment when the rule format changes. */
+    version: number;
+    /** Mode applied when no rule matches. */
+    default: 'sync' | 'local-only';
+    /** First-match-wins rules. Glob syntax: `*`, `**`, `?`. No regex. */
+    rules: SyncPolicyRule[];
+}
+export interface SyncPolicyRule {
+    path: string;
+    mode: 'sync' | 'local-only';
+}
+/** Per-document status, returned by DocumentHandle.status(). */
+export interface DocStatus {
+    exists: boolean;
+    version: number;
+    syncMode: 'sync' | 'local-only';
+    syncState: 'synced' | 'pending' | 'conflict';
+    lastSyncedAt?: number;
+    origin?: string;
+    deleted?: boolean;
+    /** Conflict branches, only populated when syncState === 'conflict'. */
+    branches?: Array<{
+        origin: string;
+        version: number;
+        at: number;
+    }>;
+}
+/** Conflict file shape under {tenant}/__sync__/conflicts/<shardId>/<path>.conflict.json. */
+export interface ConflictFile {
+    path: string;
+    shardId: string;
+    branches: ConflictBranch[];
+}
+export interface ConflictBranch {
+    origin: string;
+    version: number;
+    content: string;
+    at: number;
+}
+/** Server-shard permission: Mode B writes + reserved __sync__ read access. */
+export declare const PERMISSION_SYNC_PEER = "sync:peer";
+/** Read/write __sync__/policy.json. Grantable to client or server shards. */
+export declare const PERMISSION_SYNC_POLICY = "sync:policy";

package/dist/documents/sync-types.js

@@ -0,0 +1,11 @@
+/*
+ * Sync vocabulary — type-only contract surface (ADR-019 revised 2026-04-19).
+ *
+ * The sync runtime lives in the installable sh3-sync shard. sh3-core exposes
+ * only the types that client shards and the shard-facing ServerShardContext
+ * share with the runtime. No runtime code in this file.
+ */
+/** Server-shard permission: Mode B writes + reserved __sync__ read access. */
+export const PERMISSION_SYNC_PEER = 'sync:peer';
+/** Read/write __sync__/policy.json. Grantable to client or server shards. */
+export const PERMISSION_SYNC_POLICY = 'sync:policy';