sh3-core 0.8.1 → 0.9.0

package/dist/Shell.svelte

@@ -25,6 +25,8 @@
   import { isAuthenticated, isLocalOwner, getUser, logout } from './auth/index';
   import iconsUrl from './assets/icons.svg';
   import GuestBanner from './auth/GuestBanner.svelte';
+  import ConsentDialog from './keys/ConsentDialog.svelte';
+  import { startServerSideStream } from './keys/revocation-bus.svelte';
 
   const authenticated = $derived(isAuthenticated());
   const user = $derived(getUser());
@@ -97,6 +99,15 @@
     }));
     return () => unbindFloatStore();
   });
+
+  // Open the server-sent events stream for key revocations.
+  // Forwards server-side revocations to the local revocation bus so that
+  // onKeyRevoked fires on the owning shard even when the user revokes from
+  // the Keys & Peers shell view (not via the shard's own ctx.keys.revoke).
+  $effect(() => {
+    const stop = startServerSideStream();
+    return stop;
+  });
 </script>
 
 <div class="shell">
@@ -165,6 +176,14 @@
       </div>
     {/each}
   </div>
+
+  <!--
+    Shell-owned consent dialog for ctx.keys.mint().
+    Mounted unconditionally so the listener is always registered; it renders
+    nothing until a shard calls ctx.keys.mint().
+    z-index 9999 (inline in the component) keeps it above all overlay layers.
+  -->
+  <ConsentDialog />
 </div>
 
 <style>

package/dist/api.d.ts

@@ -19,16 +19,16 @@ export { inspectActiveLayout, spliceIntoActiveLayout, dockIntoActiveLayout, focu
 export type { DocumentHandle, DocumentHandleOptions, DocumentFormat, DocumentMeta, DocumentChange, AutosaveController, } from './documents/types';
 export { PERMISSION_DOCUMENTS_BROWSE } from './documents/types';
 export type { BrowseCapability } from './documents/browse';
-export type { SyncHandle, SyncScope, ManifestEntry, ApplyEntry, ApplyOpts, ApplyOutcome, ApplyBatchResult, ConflictPolicy, ConflictResolution, ConflictContext, JournalEntry, ChangePage, GrantRecord, } from './documents/sync/types';
-export { PERMISSION_DOCUMENTS_SYNC, ScopeNotGrantedError, ScopeRevokedError, TenantMismatchError, } from './documents/sync/types';
-export type { SyncRegistry } from './documents/sync/registry';
-export { default as SyncGrantPicker } from './documents/sync/components/SyncGrantPicker.svelte';
-export { default as DocumentSyncExplorer } from './documents/sync/components/DocumentSyncExplorer.svelte';
+export type { SyncPolicy, SyncPolicyRule, DocStatus, ConflictFile, ConflictBranch, } from './documents/sync-types';
+export { PERMISSION_SYNC_PEER, PERMISSION_SYNC_POLICY } from './documents/sync-types';
 export { registeredShards, activeShards } from './shards/activate.svelte';
 export type { RegistryIndex, PackageEntry, PackageVersion, RequiredDependency, InstalledPackage, InstallResult, PackageMeta, } from './registry/types';
 export type { ResolvedPackage } from './registry/client';
 export { fetchRegistries, fetchBundle, buildPackageMeta } from './registry/client';
 export { validateRegistryIndex } from './registry/schema';
+export { PERMISSION_KEYS_MINT, ScopeEscalationError, ConsentDeniedError, type ShardContextKeys, type ApiKeyPublic, type MintOpts, } from './keys/types';
+export { registerConsentListener, resolveConsent, type ConsentRequest } from './keys/consent.svelte';
+export { subscribe as subscribeKeyRevocation } from './keys/revocation-bus.svelte';
 export { isAdmin, isAuthenticated, isGuest, getUser, getAuthHeader } from './auth/index';
 export type { AuthUser, AuthSession, BootConfig } from './auth/types';
 /** Runtime feature flags for target-dependent behavior. */
@@ -36,7 +36,7 @@ export declare const capabilities: {
     /** Whether this target supports hot-installing packages via dynamic import from blob URL. */
     readonly hotInstall: boolean;
 };
-export type { ServerShard, ServerShardContext } from './server-shard/types';
+export type { ServerShard, ServerShardContext, TenantDocumentAPI } from './server-shard/types';
 export type { Verb, VerbContext, ShellApi } from './verbs/types';
 export type { Scrollback } from './shell-shard/scrollback.svelte';
 export type { SessionClient } from './shell-shard/session-client.svelte';

package/dist/api.js

@@ -30,9 +30,7 @@ export { launchApp, returnToHome, unregisterApp } from './apps/lifecycle';
 // Layout inspection / mutation for advanced shards (diagnostic, etc.).
 export { inspectActiveLayout, spliceIntoActiveLayout, dockIntoActiveLayout, focusTab, focusView, collapseChild, expandChild, closeTab, } from './layout/inspection';
 export { PERMISSION_DOCUMENTS_BROWSE } from './documents/types';
-export { PERMISSION_DOCUMENTS_SYNC, ScopeNotGrantedError, ScopeRevokedError, TenantMismatchError, } from './documents/sync/types';
-export { default as SyncGrantPicker } from './documents/sync/components/SyncGrantPicker.svelte';
-export { default as DocumentSyncExplorer } from './documents/sync/components/DocumentSyncExplorer.svelte';
+export { PERMISSION_SYNC_PEER, PERMISSION_SYNC_POLICY } from './documents/sync-types';
 // Shard introspection — read-only reactive maps exposing which shards are
 // known to the host and which are currently active. Intended for diagnostic
 // and tooling shards that need to visualize framework state. Phase 9
@@ -41,6 +39,11 @@ export { default as DocumentSyncExplorer } from './documents/sync/components/Doc
 export { registeredShards, activeShards } from './shards/activate.svelte';
 export { fetchRegistries, fetchBundle, buildPackageMeta } from './registry/client';
 export { validateRegistryIndex } from './registry/schema';
+// Key mint/revoke types — client shards that declare `keys:mint` get ctx.keys.
+export { PERMISSION_KEYS_MINT, ScopeEscalationError, ConsentDeniedError, } from './keys/types';
+export { registerConsentListener, resolveConsent } from './keys/consent.svelte';
+// Revocation bus — subscribe to key revocation events (for advanced integrations).
+export { subscribe as subscribeKeyRevocation } from './keys/revocation-bus.svelte';
 // Admin mode (framework-internal components read admin status).
 export { isAdmin, isAuthenticated, isGuest, getUser, getAuthHeader } from './auth/index';
 /** Runtime feature flags for target-dependent behavior. */

package/dist/app/admin/ApiKeysView.svelte

@@ -3,14 +3,13 @@
    * Admin API Keys view — list, create, reveal, revoke API keys.
    */
 
-  interface ApiKey {
+  interface ApiKeyPublic {
     id: string;
-    key: string;
     label: string;
     createdAt: string;
   }
 
-  let keys = $state<ApiKey[]>([]);
+  let keys = $state<ApiKeyPublic[]>([]);
   let loading = $state(true);
   let error = $state<string | null>(null);
 
@@ -19,8 +18,9 @@
   let newLabel = $state('');
   let createError = $state<string | null>(null);
 
-  // Reveal state — tracks which key ids have been revealed
-  let revealed = $state<Set<string>>(new Set());
+  // Just-created key — the raw bearer value is returned once by the server.
+  // Displayed until the admin dismisses it, then never recoverable.
+  let justCreated = $state<{ id: string; key: string } | null>(null);
 
   // Delete confirmation
   let confirmingId = $state<string | null>(null);
@@ -53,9 +53,8 @@
         createError = body.error || 'Failed to create key';
         return;
       }
-      const created: ApiKey = await res.json();
-      revealed.add(created.id);
-      revealed = new Set(revealed);
+      const created: { id: string; key: string } = await res.json();
+      justCreated = { id: created.id, key: created.key };
       newLabel = '';
       showCreate = false;
       await fetchKeys();
@@ -64,15 +63,6 @@
     }
   }
 
-  function toggleReveal(id: string) {
-    if (revealed.has(id)) {
-      revealed.delete(id);
-    } else {
-      revealed.add(id);
-    }
-    revealed = new Set(revealed);
-  }
-
   async function revokeKey(id: string) {
     confirmingId = null;
     try {
@@ -80,8 +70,7 @@
         method: 'DELETE',
         credentials: 'include',
       });
-      revealed.delete(id);
-      revealed = new Set(revealed);
+      if (justCreated?.id === id) justCreated = null;
       await fetchKeys();
     } catch { /* ignore */ }
   }
@@ -92,10 +81,6 @@
     });
   }
 
-  function maskKey(key: string): string {
-    return key.slice(0, 8) + '\u2026' + key.slice(-4);
-  }
-
   fetchKeys();
 </script>
 
@@ -107,6 +92,14 @@
     </button>
   </div>
 
+  {#if justCreated}
+    <div class="admin-key-created">
+      <div class="admin-key-created-label">New key — copy now, it won't be shown again:</div>
+      <code class="admin-key-value">{justCreated.key}</code>
+      <button type="button" class="admin-btn-secondary" onclick={() => { justCreated = null; }}>Dismiss</button>
+    </div>
+  {/if}
+
   {#if showCreate}
     <form class="admin-create-form" onsubmit={(e) => { e.preventDefault(); createKey(); }}>
       <input class="admin-input" type="text" placeholder="Key label" bind:value={newLabel} />
@@ -128,12 +121,8 @@
           <div class="admin-key-info">
             <span class="admin-key-label">{k.label}</span>
             <span class="admin-key-meta">{k.id} &middot; {formatDate(k.createdAt)}</span>
-            <code class="admin-key-value">{revealed.has(k.id) ? k.key : maskKey(k.key)}</code>
           </div>
           <div class="admin-key-actions">
-            <button type="button" class="admin-btn-secondary" onclick={() => toggleReveal(k.id)}>
-              {revealed.has(k.id) ? 'Hide' : 'Reveal'}
-            </button>
             {#if confirmingId === k.id}
               <button type="button" class="admin-btn-danger" onclick={() => revokeKey(k.id)}>Confirm</button>
               <button type="button" class="admin-btn-secondary" onclick={() => { confirmingId = null; }}>Cancel</button>

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/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';

package/dist/documents/types.d.ts

@@ -1,7 +1,8 @@
 /**
  * Manifest permission string: grants tenant-wide document observation
- * (`ctx.browse`) and sync registry visibility (`ctx.syncRegistry`).
- * Read-only; writes still flow through the shard's own `ctx.documents()`.
+ * via `ctx.browse` (read-only enumeration and change subscription across
+ * every shard's documents for the active tenant). Writes still flow
+ * through the owning shard's own `ctx.documents()` handle.
  */
 export declare const PERMISSION_DOCUMENTS_BROWSE = "documents:browse";
 /**
@@ -25,6 +26,20 @@ export interface DocumentMeta {
     size: number;
     /** Last modified timestamp in epoch milliseconds. */
     lastModified: number;
+    /** Monotonic per-document version; primary-authoritative. */
+    version?: number;
+    /** 'sync' or 'local-only', cached from policy.json at write time. */
+    syncMode?: 'sync' | 'local-only';
+    /** 'synced' | 'pending' | 'conflict'. */
+    syncState?: 'synced' | 'pending' | 'conflict';
+    /** Replica's view of primary's version at last confirmed sync. */
+    lastKnownVersion?: number;
+    /** Epoch ms; when replica/primary last agreed on content. */
+    lastSyncedAt?: number;
+    /** Peer id that produced this content (set by Mode B). */
+    origin?: string;
+    /** Tombstone marker for deleted docs. */
+    deleted?: boolean;
 }
 /** Change notification payload delivered to watch callbacks. */
 export interface DocumentChange {
@@ -33,6 +48,7 @@ export interface DocumentChange {
     tenantId: string;
     shardId: string;
 }
+import type { DocStatus } from './sync-types';
 /**
  * File-oriented backend for the document zone.
  *
@@ -68,6 +84,19 @@ export interface DocumentBackend {
     listAllDocuments(tenantId: string): Promise<Array<DocumentMeta & {
         shardId: string;
     }>>;
+    /**
+     * Read sync-state metadata for a doc without fetching content.
+     * Returns null if the doc does not exist. Optional because only
+     * sync-aware backends (HttpDocumentBackend) support it.
+     */
+    readMeta?(tenantId: string, shardId: string, path: string): Promise<DocStatus | null>;
+    /**
+     * Resolve a conflict by picking a branch or supplying fresh content.
+     * Optional; only supported by HttpDocumentBackend in v1.
+     */
+    resolve?(tenantId: string, shardId: string, path: string, choice: 'local' | 'remote' | {
+        origin: string;
+    } | string): Promise<void>;
 }
 /**
  * Shard-facing document handle returned by `ctx.documents()`. Binds
@@ -84,6 +113,15 @@ export interface DocumentHandle {
     delete(path: string): Promise<void>;
     /** Check existence without reading content. */
     exists(path: string): Promise<boolean>;
+    /** Fetch sync-state metadata for a path. Null if the doc does not exist. */
+    status(path: string): Promise<DocStatus | null>;
+    /**
+     * Resolve a conflict. `'local'` keeps the local branch; any other
+     * origin string picks the named branch from the conflict bucket.
+     */
+    resolveConflict(path: string, choice: 'local' | 'remote' | {
+        origin: string;
+    } | string): Promise<void>;
     /**
      * Subscribe to change notifications within this handle's scope.
      * Returns an unsubscribe function.

package/dist/documents/types.js

@@ -11,7 +11,8 @@
  */
 /**
  * Manifest permission string: grants tenant-wide document observation
- * (`ctx.browse`) and sync registry visibility (`ctx.syncRegistry`).
- * Read-only; writes still flow through the shard's own `ctx.documents()`.
+ * via `ctx.browse` (read-only enumeration and change subscription across
+ * every shard's documents for the active tenant). Writes still flow
+ * through the owning shard's own `ctx.documents()` handle.
  */
 export const PERMISSION_DOCUMENTS_BROWSE = 'documents:browse';