sh3-core 0.8.2 → 0.9.0

package/dist/api.d.ts

@@ -19,11 +19,8 @@ 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';
@@ -39,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

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

package/dist/keys/ConsentDialog.svelte

@@ -4,7 +4,7 @@
 
   Mounted once by the shell at boot; never by shards.
 
-  Security: all shard-provided strings (shardId, label, scope, connectorId)
+  Security: all shard-provided strings (shardId, label, scope, peerId)
   are rendered as plain text via Svelte's default interpolation — no @html.
 -->
 <script lang="ts">
@@ -45,9 +45,9 @@
             <code class="sh3-consent-scope">{s}</code>
           {/each}
         </dd>
-        {#if current.connectorId}
-          <dt>Connector</dt>
-          <dd>{current.connectorId}</dd>
+        {#if current.peerRole || current.peerId}
+          <dt>Peer</dt>
+          <dd>{current.peerRole ?? '—'}{current.peerId ? ` · ${current.peerId}` : ''}</dd>
         {/if}
         {#if current.expiresIn}
           <dt>Expires in</dt>

package/dist/keys/consent.test.js

@@ -14,13 +14,14 @@ describe('consent runtime', () => {
             queueMicrotask(() => resolveConsent(req.requestId, true));
         });
         cleanups.push(off);
-        await requestConsent('shard-a', { label: 'My key', scopes: ['documents:sync'], connectorId: 'peer-x' });
+        await requestConsent('shard-a', { label: 'My key', scopes: ['sync:peer'], peerRole: 'replica', peerId: 'peer-x' });
         expect(received).toHaveLength(1);
         const req = received[0];
         expect(req.shardId).toBe('shard-a');
         expect(req.label).toBe('My key');
-        expect(req.scopes).toEqual(['documents:sync']);
-        expect(req.connectorId).toBe('peer-x');
+        expect(req.scopes).toEqual(['sync:peer']);
+        expect(req.peerRole).toBe('replica');
+        expect(req.peerId).toBe('peer-x');
         expect(typeof req.requestId).toBe('string');
     });
     it('resolves true when approved', async () => {

package/dist/keys/types.d.ts

@@ -6,14 +6,16 @@ export interface ApiKeyPublic {
     ownerUserId: string | null;
     mintedByShardId: string | null;
     scopes: string[];
-    connectorId?: string;
+    peerRole?: 'primary' | 'replica';
+    peerId?: string;
     createdAt: string;
     expiresAt?: string;
 }
 export interface MintOpts {
     label: string;
     scopes: string[];
-    connectorId?: string;
+    peerRole?: 'primary' | 'replica';
+    peerId?: string;
     expiresIn?: number;
 }
 export interface ShardContextKeys {

package/dist/server-shard/types.d.ts

@@ -10,8 +10,51 @@
  * The server bundle is a separate ESM file whose default export conforms
  * to the `ServerShard` interface.
  */
-import type { SyncHandle } from '../documents/sync/types';
-import type { SyncRegistry } from '../documents/sync/registry';
+import type { DocumentMeta } from '../documents/types';
+import type { SyncPolicy, ConflictFile } from '../documents/sync-types';
+/**
+ * Per-tenant document API exposed to server shards via
+ * `ServerShardContext.documents(tenantId)`. Every method is
+ * permission-checked by the host at call time.
+ */
+export interface TenantDocumentAPI {
+    read(shardId: string, path: string): Promise<string | null>;
+    exists(shardId: string, path: string): Promise<boolean>;
+    list(shardId: string): Promise<DocumentMeta[]>;
+    listAll(): Promise<Array<DocumentMeta & {
+        shardId: string;
+    }>>;
+    write(shardId: string, path: string, content: string | Uint8Array, metadata?: Record<string, unknown>): Promise<{
+        version: number;
+        syncState: 'synced' | 'pending';
+    }>;
+    delete(shardId: string, path: string): Promise<void>;
+    applyFromPeer(input: {
+        shardId: string;
+        path: string;
+        content: string | Uint8Array;
+        incomingVersion: number;
+        expectedLocalVersion: number;
+        origin: string;
+        deleted?: boolean;
+        metadata?: Record<string, unknown>;
+    }): Promise<{
+        applied: true;
+        version: number;
+    } | {
+        applied: false;
+        reason: 'stale' | 'conflict' | 'conflict-extended';
+    }>;
+    getTick(): Promise<number>;
+    readPolicy(): Promise<SyncPolicy | null>;
+    writePolicy(policy: SyncPolicy): Promise<void>;
+    listConflicts(): Promise<Array<{
+        shardId: string;
+        path: string;
+    }>>;
+    readConflict(shardId: string, path: string): Promise<ConflictFile | null>;
+    resolveConflict(shardId: string, path: string, choice: 'local' | string | Uint8Array): Promise<void>;
+}
 /**
  * Context provided by sh3-server when mounting a server shard's routes.
  */
@@ -41,14 +84,16 @@ export interface ServerShardContext {
      * WebSocket upgrade registration — unchanged from 0.8.1.
      */
     wsRegister?: (onConnect: (ws: any, c: any) => void) => any;
+    /** Tenant ids that currently have doc content on this server. */
+    tenants(): string[];
+    /** Per-tenant document API, permission-checked per operation. */
+    documents(tenant: string): TenantDocumentAPI;
     /**
-     * Obtain a tenant-scoped SyncHandle from a server-side route handler.
-     * The handle enforces GrantRecord checks exactly like the client-side
-     * one. Throws if the shard's manifest does not declare `documents:sync`.
+     * Declare the server's role for a tenant. Called by shards with
+     * `sync:peer` permission. No-op unless the caller holds it.
+     * Absent => 'primary' behavior at the store.
      */
-    sync: (tenantId: string, connectorId: string) => Promise<SyncHandle>;
-    /** Tenant-scoped SyncRegistry accessor — grant enumeration/listing. */
-    syncRegistry: (tenantId: string) => SyncRegistry;
+    setPeerRole(tenant: string, role: 'primary' | 'replica'): void;
 }
 /**
  * The interface a server shard bundle must default-export.
@@ -64,6 +109,8 @@ export interface ServerShard {
      * May be async if the shard needs to initialise resources before serving.
      */
     routes: (router: HonoLike, context: ServerShardContext) => void | Promise<void>;
+    /** Optional shutdown hook. Called once on server SIGTERM/SIGINT. */
+    teardown?(): void | Promise<void>;
 }
 /**
  * Hono MiddlewareHandler type — duplicated here to avoid importing hono