sh3-core 0.8.2 → 0.9.1

package/dist/documents/sync/serialization.test.js

@@ -1,26 +0,0 @@
-import { describe, it, expect, beforeEach } from 'vitest';
-import { MemoryDocumentBackend } from '../backends';
-import { readJson, writeJson, listJsonPaths } from './serialization';
-import { SYNC_RESERVED_SHARD_ID } from './types';
-describe('sync serialization', () => {
-    let backend;
-    beforeEach(() => { backend = new MemoryDocumentBackend(); });
-    it('writes and reads JSON round-trip', async () => {
-        await writeJson(backend, 'tenant-a', 'foo/bar.json', { hello: 'world', n: 7 });
-        const out = await readJson(backend, 'tenant-a', 'foo/bar.json');
-        expect(out).toEqual({ hello: 'world', n: 7 });
-    });
-    it('returns null when a path is absent', async () => {
-        expect(await readJson(backend, 'tenant-a', 'missing.json')).toBeNull();
-    });
-    it('lists JSON paths under a prefix', async () => {
-        await writeJson(backend, 't', 'grants/a.json', { a: 1 });
-        await writeJson(backend, 't', 'grants/b.json', { b: 2 });
-        await writeJson(backend, 't', 'other/c.json', { c: 3 });
-        const paths = await listJsonPaths(backend, 't', 'grants/');
-        expect(paths.sort()).toEqual(['grants/a.json', 'grants/b.json']);
-    });
-    it('uses SYNC_RESERVED_SHARD_ID', () => {
-        expect(SYNC_RESERVED_SHARD_ID).toBe('__sync__');
-    });
-});

package/dist/documents/sync/singleton.d.ts

@@ -1,11 +0,0 @@
-import type { DocumentBackend } from '../types';
-import { SyncEngine } from './engine';
-import { type SyncRegistry } from './registry';
-interface Bundle {
-    engine: SyncEngine;
-    registry: SyncRegistry;
-}
-export declare function getSyncBundle(backend: DocumentBackend, tenantId: string): Promise<Bundle>;
-/** Test-only reset. */
-export declare function __resetSyncBundlesForTest(): void;
-export {};

package/dist/documents/sync/singleton.js

@@ -1,26 +0,0 @@
-/*
- * Per-tenant SyncEngine singleton. Lazily initialised on first
- * ctx.sync() call. The journal appender hook is registered once
- * when the engine is first built so regular shard writes feed
- * the journal for all future connectors.
- */
-import { setJournalAppender } from '../journal-hook';
-import { SyncEngine } from './engine';
-import { createSyncRegistry } from './registry';
-const bundles = new Map();
-export async function getSyncBundle(backend, tenantId) {
-    const existing = bundles.get(tenantId);
-    if (existing)
-        return existing;
-    const engine = new SyncEngine(backend, tenantId);
-    await engine.init();
-    const registry = createSyncRegistry(backend, tenantId);
-    setJournalAppender(async (e) => { await engine.journal.append(e); });
-    const bundle = { engine, registry };
-    bundles.set(tenantId, bundle);
-    return bundle;
-}
-/** Test-only reset. */
-export function __resetSyncBundlesForTest() {
-    bundles.clear();
-}

package/dist/documents/sync/tombstones.d.ts

@@ -1,19 +0,0 @@
-import type { DocumentBackend } from '../types';
-export interface TombstoneRecord {
-    deletedAt: number;
-    lastHash: string;
-}
-export interface TombstoneEntry extends TombstoneRecord {
-    shardId: string;
-    path: string;
-}
-export declare class TombstoneStore {
-    private backend;
-    private tenantId;
-    constructor(backend: DocumentBackend, tenantId: string);
-    record(shardId: string, path: string, lastHash: string, deletedAt: number): Promise<void>;
-    get(shardId: string, path: string): Promise<TombstoneRecord | null>;
-    clear(shardId: string, path: string): Promise<void>;
-    listByShard(shardId: string): Promise<TombstoneEntry[]>;
-    listAll(): Promise<TombstoneEntry[]>;
-}

package/dist/documents/sync/tombstones.js

@@ -1,58 +0,0 @@
-/*
- * Tombstone store — records deletion metadata so sync connectors can
- * distinguish "never existed" from "was deleted." Backed by JSON docs
- * under the reserved sync shardId. GC is driven by the engine, not here.
- */
-import { readJson, writeJson, deletePath, listJsonPaths } from './serialization';
-const PREFIX = 'tombstones/';
-function key(shardId, path) {
-    return `${PREFIX}${shardId}__${encodeURIComponent(path)}.json`;
-}
-export class TombstoneStore {
-    constructor(backend, tenantId) {
-        this.backend = backend;
-        this.tenantId = tenantId;
-    }
-    async record(shardId, path, lastHash, deletedAt) {
-        await writeJson(this.backend, this.tenantId, key(shardId, path), {
-            deletedAt,
-            lastHash,
-        });
-    }
-    async get(shardId, path) {
-        return readJson(this.backend, this.tenantId, key(shardId, path));
-    }
-    async clear(shardId, path) {
-        await deletePath(this.backend, this.tenantId, key(shardId, path));
-    }
-    async listByShard(shardId) {
-        const prefix = `${PREFIX}${shardId}__`;
-        const paths = await listJsonPaths(this.backend, this.tenantId, prefix);
-        const out = [];
-        for (const p of paths) {
-            const rec = await readJson(this.backend, this.tenantId, p);
-            if (!rec)
-                continue;
-            const originalPath = decodeURIComponent(p.slice(prefix.length, -'.json'.length));
-            out.push(Object.assign({ shardId, path: originalPath }, rec));
-        }
-        return out;
-    }
-    async listAll() {
-        const paths = await listJsonPaths(this.backend, this.tenantId, PREFIX);
-        const out = [];
-        for (const p of paths) {
-            const rec = await readJson(this.backend, this.tenantId, p);
-            if (!rec)
-                continue;
-            const rest = p.slice(PREFIX.length, -'.json'.length);
-            const sep = rest.indexOf('__');
-            if (sep < 0)
-                continue;
-            const shardId = rest.slice(0, sep);
-            const path = decodeURIComponent(rest.slice(sep + 2));
-            out.push(Object.assign({ shardId, path }, rec));
-        }
-        return out;
-    }
-}

package/dist/documents/sync/tombstones.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/documents/sync/tombstones.test.js

@@ -1,37 +0,0 @@
-import { describe, it, expect, beforeEach } from 'vitest';
-import { MemoryDocumentBackend } from '../backends';
-import { TombstoneStore } from './tombstones';
-describe('TombstoneStore', () => {
-    let backend;
-    let store;
-    beforeEach(() => {
-        backend = new MemoryDocumentBackend();
-        store = new TombstoneStore(backend, 'tenant-a');
-    });
-    it('records and retrieves a tombstone', async () => {
-        await store.record('shard-x', 'dir/file.md', 'hash123', 1000);
-        const t = await store.get('shard-x', 'dir/file.md');
-        expect(t).toEqual({ deletedAt: 1000, lastHash: 'hash123' });
-    });
-    it('returns null for non-tombstoned paths', async () => {
-        expect(await store.get('shard-x', 'absent.md')).toBeNull();
-    });
-    it('clears a tombstone (on upsert of same path)', async () => {
-        await store.record('shard-x', 'a.md', 'h', 1);
-        await store.clear('shard-x', 'a.md');
-        expect(await store.get('shard-x', 'a.md')).toBeNull();
-    });
-    it('lists tombstones within a shard', async () => {
-        await store.record('shard-x', 'a.md', 'h1', 1);
-        await store.record('shard-x', 'b.md', 'h2', 2);
-        await store.record('shard-y', 'c.md', 'h3', 3);
-        const list = await store.listByShard('shard-x');
-        expect(list.map((t) => t.path).sort()).toEqual(['a.md', 'b.md']);
-    });
-    it('lists all tombstones across shards', async () => {
-        await store.record('shard-x', 'a.md', 'h1', 1);
-        await store.record('shard-y', 'c.md', 'h3', 3);
-        const all = await store.listAll();
-        expect(all.length).toBe(2);
-    });
-});

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

@@ -1,116 +0,0 @@
-/** Permission string required in a shard manifest to obtain ctx.sync(). */
-export declare const PERMISSION_DOCUMENTS_SYNC = "documents:sync";
-/** Reserved shardId used to persist sync metadata (journal, tombstones, cursors, grants). */
-export declare const SYNC_RESERVED_SHARD_ID = "__sync__";
-export type SyncScope = {
-    kind: 'shard';
-    shardId: string;
-} | {
-    kind: 'tenant';
-} | {
-    kind: 'path';
-    shardId: string;
-    prefix: string;
-};
-export interface ManifestEntry {
-    path: string;
-    shardId: string;
-    hash: string;
-    size: number;
-    lastModified: number;
-    tombstone?: {
-        deletedAt: number;
-    };
-}
-export interface ApplyEntry {
-    path: string;
-    shardId: string;
-    op: 'upsert' | 'delete';
-    content?: string | ArrayBuffer;
-    remoteHash: string;
-    remoteMtime: number;
-}
-export interface ApplyOpts {
-    onConflict?: ConflictPolicy;
-    expectedLocalHash?: string;
-}
-export type ApplyOutcome = {
-    status: 'applied';
-    newHash: string;
-} | {
-    status: 'skipped-identical';
-} | {
-    status: 'conflict';
-    resolution: ConflictResolution;
-};
-export interface ApplyBatchResult {
-    applied: Array<{
-        path: string;
-        shardId: string;
-        newHash: string;
-    }>;
-    skipped: Array<{
-        path: string;
-        shardId: string;
-        reason: 'identical';
-    }>;
-    conflicts: ConflictResolution[];
-}
-export interface ConflictResolution {
-    path: string;
-    shardId: string;
-    localHash: string;
-    remoteHash: string;
-    conflictArtifactPath: string;
-    base?: {
-        hash: string;
-    };
-}
-export interface ConflictContext {
-    path: string;
-    shardId: string;
-    localHash: string;
-    remoteHash: string;
-    baseHash?: string;
-}
-export type ConflictPolicy = 'default' | 'remote-wins' | 'local-wins' | 'keep-both' | ((ctx: ConflictContext) => Promise<'remote-wins' | 'local-wins' | 'keep-both'>);
-export interface JournalEntry {
-    seq: number;
-    ts: number;
-    shardId: string;
-    path: string;
-    op: 'upsert' | 'delete';
-    hash: string | null;
-}
-export interface ChangePage {
-    entries: JournalEntry[];
-    nextCursor: string;
-    hasMore: boolean;
-    truncated?: boolean;
-}
-export interface GrantRecord {
-    connectorId: string;
-    scope: SyncScope;
-    grantedAt: number;
-}
-export interface SyncHandle {
-    readonly connectorId: string;
-    grantedScopes(): Promise<SyncScope[]>;
-    getManifest(scope: SyncScope): Promise<ManifestEntry[]>;
-    changesSince(scope: SyncScope, cursor?: string): Promise<ChangePage>;
-    ack(scope: SyncScope, cursor: string): Promise<void>;
-    apply(scope: SyncScope, entry: ApplyEntry, opts?: ApplyOpts): Promise<ApplyOutcome>;
-    applyBatch(scope: SyncScope, manifest: ApplyEntry[], opts?: ApplyOpts): Promise<ApplyBatchResult>;
-    forget(scope: SyncScope, path: string): Promise<void>;
-}
-export declare class ScopeNotGrantedError extends Error {
-    readonly scope: SyncScope;
-    constructor(scope: SyncScope);
-}
-export declare class ScopeRevokedError extends Error {
-    readonly scope: SyncScope;
-    constructor(scope: SyncScope);
-}
-export declare class TenantMismatchError extends Error {
-    constructor();
-}

package/dist/documents/sync/types.js

@@ -1,27 +0,0 @@
-/*
- * Document Sync API types. See docs/superpowers/specs/2026-04-14-document-sync-api-design.md.
- */
-/** Permission string required in a shard manifest to obtain ctx.sync(). */
-export const PERMISSION_DOCUMENTS_SYNC = 'documents:sync';
-/** Reserved shardId used to persist sync metadata (journal, tombstones, cursors, grants). */
-export const SYNC_RESERVED_SHARD_ID = '__sync__';
-export class ScopeNotGrantedError extends Error {
-    constructor(scope) {
-        super(`Scope not granted: ${JSON.stringify(scope)}`);
-        this.scope = scope;
-        this.name = 'ScopeNotGrantedError';
-    }
-}
-export class ScopeRevokedError extends Error {
-    constructor(scope) {
-        super(`Scope revoked during operation: ${JSON.stringify(scope)}`);
-        this.scope = scope;
-        this.name = 'ScopeRevokedError';
-    }
-}
-export class TenantMismatchError extends Error {
-    constructor() {
-        super('Sync handle tenantId does not match current session');
-        this.name = 'TenantMismatchError';
-    }
-}

package/dist/documents/sync/write-hook.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/documents/sync/write-hook.test.js

@@ -1,36 +0,0 @@
-// packages/sh3-core/src/documents/sync/write-hook.test.ts
-import { describe, it, expect, beforeEach } from 'vitest';
-import { MemoryDocumentBackend } from '../backends';
-import { __setDocumentBackend, __setTenantId } from '../config';
-import { createDocumentHandle } from '../handle';
-import { SyncEngine } from './engine';
-import { setJournalAppender, clearJournalAppender } from '../journal-hook';
-describe('regular document writes feed the sync journal', () => {
-    let backend;
-    let engine;
-    beforeEach(async () => {
-        backend = new MemoryDocumentBackend();
-        __setDocumentBackend(backend);
-        __setTenantId('tenant-a');
-        engine = new SyncEngine(backend, 'tenant-a');
-        await engine.init();
-        setJournalAppender(async (e) => { await engine.journal.append(e); });
-    });
-    it('appends upsert to journal when shard writes via ctx.documents()', async () => {
-        const h = createDocumentHandle('tenant-a', 'shard-x', backend, { format: 'text' });
-        await h.write('a.md', 'hello');
-        const page = await engine.journal.changesSince({ kind: 'tenant' });
-        expect(page.entries.map((e) => `${e.shardId}:${e.path}:${e.op}`)).toEqual([
-            'shard-x:a.md:upsert',
-        ]);
-        clearJournalAppender();
-    });
-    it('appends delete to journal', async () => {
-        const h = createDocumentHandle('tenant-a', 'shard-x', backend, { format: 'text' });
-        await h.write('a.md', 'hello');
-        await h.delete('a.md');
-        const page = await engine.journal.changesSince({ kind: 'tenant' });
-        expect(page.entries.map((e) => e.op)).toEqual(['upsert', 'delete']);
-        clearJournalAppender();
-    });
-});

package/dist/server-sync.d.ts

@@ -1,6 +0,0 @@
-export { getSyncBundle } from './documents/sync/singleton';
-export { createSyncHandle } from './documents/sync/handle';
-export { createSyncRegistry } from './documents/sync/registry';
-export type { SyncHandle } from './documents/sync/types';
-export type { SyncRegistry } from './documents/sync/registry';
-export type { DocumentBackend, DocumentMeta } from './documents/types';