ofsync-shared-core 0.2.0-alpha.0

package/README.md

@@ -0,0 +1,28 @@
+# ofsync-shared-core
+
+`ofsync-shared-core` is the host-side sync orchestration core for the `of*` ecosystem.
+
+This package standardizes offline-first synchronization flow for multi-domain host apps, while keeping:
+- **offline-first** behavior,
+- **database agnostic** runtime contracts,
+- **platform agnostic** integration boundaries.
+
+## Scope
+- local outbox/inbox orchestration,
+- sync scheduling + retry/backoff policy,
+- conflict pipeline with resolver hooks,
+- cross-domain local projection/event orchestration,
+- transport bridge to `ofsync-server` via adapter contracts.
+
+## Boundary Rules
+- keep business logic inside `of[domain]-shared-core`,
+- do not hardcode DB drivers or platform APIs in core runtime,
+- consume generic primitives from `ofcore` and domain contracts from domain shared-cores.
+
+## Status
+- Current status: **phase 0-5 implemented**.
+- Source RFC: `docs/rfc/007-ofsync-shared-core-offline-first-host-sync-orchestration.md` (in POS workspace).
+
+## Documentation
+- Documentation hub: `docs/00-DOCUMENTATION-HUB.md`
+- Architecture intent: `docs/10-ARCHITECTURE-INTENT.md`

package/dist/OfsyncCore.d.ts

@@ -0,0 +1,76 @@
+import type { ActivitySink, CoreAdapterRegistry, CoreRuntime, CoreRuntimeStartOptions, HttpAdapter, LoggerAdapter, PlatformAdapter, SocketAdapter, DbAdapter } from 'ofcore';
+import type { ReadonlyStore, Store } from 'ofcore';
+import type { OutboxItem, SyncChange, SyncPolicy, SyncScope } from './contracts/SyncContract';
+import type { DomainBridge } from './services/DomainBridge';
+import type { CheckpointStore } from './services/InMemoryCheckpointStore';
+import type { OutboxStore } from './services/InMemoryOutboxStore';
+import { type ConflictResolver } from './services/ConflictResolver';
+import type { SyncTransport } from './services/SyncTransport';
+export interface OfsyncRuntimeState {
+    phase: 'idle' | 'starting' | 'started' | 'syncing' | 'stopping' | 'stopped' | 'error';
+    started: boolean;
+    syncing: boolean;
+    startCount: number;
+    stopCount: number;
+    syncCount: number;
+    lastError: string | null;
+    lastTransitionAt: string;
+}
+export interface OfsyncCoreOptions {
+    policy?: Partial<SyncPolicy>;
+    transport?: SyncTransport;
+    outboxStore?: OutboxStore;
+    checkpointStore?: CheckpointStore;
+    conflictResolvers?: ConflictResolver[];
+    projectionHook?: (change: SyncChange, scope: SyncScope) => Promise<void> | void;
+}
+export declare class OfsyncCore {
+    private readonly runtime;
+    private readonly runtimeStateStore;
+    private readonly bridges;
+    private readonly policy;
+    private readonly transport?;
+    private readonly outboxStore;
+    private readonly checkpointStore;
+    private readonly conflictResolvers;
+    private readonly projectionHook?;
+    private schedulerTimer?;
+    readonly runtimeStore: ReadonlyStore<OfsyncRuntimeState>;
+    constructor(runtime: CoreRuntime<never, never>, runtimeStateStore: Store<OfsyncRuntimeState>, options?: OfsyncCoreOptions);
+    static builder(): OfsyncCoreBuilder;
+    get registry(): CoreAdapterRegistry | undefined;
+    getPolicy(): SyncPolicy;
+    registerDomainBridge(bridge: DomainBridge): void;
+    listDomainBridges(): string[];
+    enqueueLocalChange(change: SyncChange, idempotencyKey?: string): Promise<OutboxItem>;
+    start(options?: CoreRuntimeStartOptions): Promise<void>;
+    stop(): Promise<void>;
+    startSync(scope: SyncScope): Promise<void>;
+    stopSync(): Promise<void>;
+    isStarted(): boolean;
+    startScheduler(scope: SyncScope): void;
+    stopScheduler(): void;
+    notifyOnline(scope: SyncScope): Promise<void>;
+    private processOutbox;
+    private applyRemoteChanges;
+    private resolveConflicts;
+}
+export declare class OfsyncCoreBuilder {
+    private readonly runtimeBuilder;
+    private options;
+    constructor();
+    withPlatformAdapter(factory: (core: CoreRuntime<any, any>) => PlatformAdapter): this;
+    withDbAdapter(factory: (core: CoreRuntime<any, any>) => DbAdapter): this;
+    withHttpAdapter(factory: (core: CoreRuntime<any, any>) => HttpAdapter): this;
+    withSocketAdapter(factory: (core: CoreRuntime<any, any>) => SocketAdapter): this;
+    withLoggerAdapter(factory: (core: CoreRuntime<any, any>) => LoggerAdapter): this;
+    withActivitySink(factory: (core: CoreRuntime<any, any>) => ActivitySink): this;
+    withExtension(name: string, factory: (core: CoreRuntime<any, any>) => unknown): this;
+    withPolicy(policy: Partial<SyncPolicy>): this;
+    withTransport(transport: SyncTransport): this;
+    withOutboxStore(store: OutboxStore): this;
+    withCheckpointStore(store: CheckpointStore): this;
+    withConflictResolvers(resolvers: ConflictResolver[]): this;
+    withProjectionHook(hook: (change: SyncChange, scope: SyncScope) => Promise<void> | void): this;
+    build(): OfsyncCore;
+}

package/dist/adapters/OfsyncHttpTransport.d.ts

@@ -0,0 +1,44 @@
+import type { HttpAdapter } from 'ofcore';
+import type { ConflictItem, OutboxItem, SyncScope } from '../contracts/SyncContract';
+import type { SyncPullResult, SyncPushResult, SyncTransport } from '../services/SyncTransport';
+export interface OfsyncHttpTransportOptions {
+    baseUrl: string;
+    httpAdapter: HttpAdapter;
+    getAccessToken?: () => string | null | undefined | Promise<string | null | undefined>;
+    nowIso?: () => string;
+}
+export declare class OfsyncTransportError extends Error {
+    readonly code: string;
+    readonly retryable: boolean;
+    readonly status?: number;
+    constructor(code: string, message: string, retryable?: boolean, status?: number);
+}
+export declare class OfsyncHttpTransport implements SyncTransport {
+    private readonly options;
+    constructor(options: OfsyncHttpTransportOptions);
+    private nowIso;
+    private buildHeaders;
+    private normalizeUrl;
+    private parseFailure;
+    push(params: {
+        scope: SyncScope;
+        outbox: OutboxItem[];
+    }): Promise<SyncPushResult>;
+    pull(params: {
+        scope: SyncScope;
+        cursor: string | null;
+        limit: number;
+    }): Promise<SyncPullResult>;
+    listConflicts(params: {
+        scope: SyncScope;
+    }): Promise<ConflictItem[]>;
+    resolveConflicts(params: {
+        scope: SyncScope;
+        resolutions: Array<{
+            conflictId: string;
+            action: 'APPLY_REMOTE' | 'KEEP_LOCAL' | 'MANUAL_MERGE';
+        }>;
+    }): Promise<{
+        resolvedCount: number;
+    }>;
+}

package/dist/api.d.ts

@@ -0,0 +1,9 @@
+import type { CoreRuntimeStartOptions } from 'ofcore';
+import { OfsyncCore } from './OfsyncCore';
+import type { OfsyncCoreOptions } from './OfsyncCore';
+import type { DomainBridge } from './services/DomainBridge';
+import type { SyncScope } from './contracts/SyncContract';
+export declare function createSyncRuntime(options?: OfsyncCoreOptions): OfsyncCore;
+export declare function registerDomainBridge(runtime: OfsyncCore, bridge: DomainBridge): void;
+export declare function startSync(runtime: OfsyncCore, scope: SyncScope, runtimeStartOptions?: CoreRuntimeStartOptions): Promise<void>;
+export declare function stopSync(runtime: OfsyncCore): Promise<void>;

package/dist/contracts/SyncContract.d.ts

@@ -0,0 +1,59 @@
+export interface SyncScope {
+    tenantId?: string;
+    branchId?: string;
+    deviceId?: string;
+}
+export type SyncChangeType = 'CREATE' | 'UPDATE' | 'DELETE';
+export interface SyncChange {
+    id: string;
+    domain: string;
+    entity: string;
+    type: SyncChangeType;
+    recordId: string;
+    payload: Record<string, unknown>;
+    occurredAt: string;
+    scope?: SyncScope;
+}
+export interface OutboxItem {
+    outboxId: string;
+    idempotencyKey: string;
+    change: SyncChange;
+    retryCount: number;
+    status: 'PENDING' | 'IN_FLIGHT' | 'FAILED' | 'APPLIED';
+    lastError?: string;
+    createdAt: string;
+    updatedAt: string;
+}
+export type ConflictCode = 'VERSION_CONFLICT' | 'SCOPE_CONFLICT' | 'REFERENCE_CONFLICT' | 'BUSINESS_RULE_CONFLICT' | 'UNKNOWN_CONFLICT';
+export interface ConflictItem {
+    conflictId: string;
+    changeId: string;
+    domain: string;
+    entity: string;
+    recordId: string;
+    code: ConflictCode;
+    message: string;
+    retryable: boolean;
+    scope?: SyncScope;
+    details?: Record<string, unknown>;
+}
+export interface SyncPolicy {
+    batchSize: number;
+    maxRetry: number;
+    scheduler: {
+        mode: 'manual' | 'interval';
+        intervalMs?: number;
+        onlineTrigger?: boolean;
+    };
+    retryBackoff: {
+        strategy: 'none' | 'fixed' | 'exponential-jitter';
+        baseDelayMs?: number;
+        maxDelayMs?: number;
+    };
+}
+export interface SyncCursor {
+    scopeKey: string;
+    value: string | null;
+    updatedAt: string;
+}
+export declare const DEFAULT_SYNC_POLICY: SyncPolicy;

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export * from './contracts/SyncContract';
+export * from './services/DomainBridge';
+export * from './services/SyncTransport';
+export * from './services/InMemoryOutboxStore';
+export * from './services/InMemoryCheckpointStore';
+export * from './services/ConflictResolver';
+export * from './runtime/ContractStage';
+export * from './OfsyncCore';
+export * from './api';
+export * from './adapters/OfsyncHttpTransport';

package/dist/index.esm.js

@@ -0,0 +1 @@
+var d={batchSize:200,maxRetry:5,scheduler:{mode:"manual",onlineTrigger:!0},retryBackoff:{strategy:"exponential-jitter",baseDelayMs:500,maxDelayMs:3e4}};var y=class{constructor(){this.rows=new Map}async enqueue(t){this.rows.set(t.outboxId,t)}async listPending(t){return[...this.rows.values()].filter(e=>e.status==="PENDING"||e.status==="FAILED").sort((e,n)=>e.createdAt.localeCompare(n.createdAt)).slice(0,Math.max(0,t))}async findByIdempotencyKey(t){for(let e of this.rows.values())if(e.idempotencyKey===t)return e;return null}async update(t){this.rows.set(t.outboxId,t)}async remove(t){this.rows.delete(t)}};var h=class{constructor(){this.rows=new Map}async get(t){return this.rows.has(t)?this.rows.get(t):null}async set(t,e){this.rows.set(t,e)}};function f(r){return r.code==="VERSION_CONFLICT"?{conflictId:r.conflictId,action:"APPLY_REMOTE"}:r.code==="SCOPE_CONFLICT"?{conflictId:r.conflictId,action:"MANUAL_MERGE"}:{conflictId:r.conflictId,action:"KEEP_LOCAL"}}var _="phase1-runtime-skeleton";import{CoreRuntime as C}from"ofcore";import{InMemoryDbAdapter as I}from"ofcore";import{asReadonlyStore as w,createStore as v}from"ofcore";function x(r={}){return{...d,...r,scheduler:{...d.scheduler,...r.scheduler||{}},retryBackoff:{...d.retryBackoff,...r.retryBackoff||{}}}}function A(r){return`${r.tenantId||"__standalone__"}::${r.branchId||"__all__"}::${r.deviceId||"__device__"}`}var u=class{constructor(t,e,n={}){this.runtime=t;this.runtimeStateStore=e;this.bridges=new Map;this.runtimeStore=w(this.runtimeStateStore),this.policy=x(n.policy),this.transport=n.transport,this.outboxStore=n.outboxStore||new y,this.checkpointStore=n.checkpointStore||new h,this.conflictResolvers=n.conflictResolvers||[],this.projectionHook=n.projectionHook}static builder(){return new S}get registry(){return this.runtime.registry}getPolicy(){return this.policy}registerDomainBridge(t){let e=t.domain.trim();if(!e)throw new Error("DomainBridge.domain is required");if(this.bridges.has(e))throw new Error(`DomainBridge for domain "${e}" is already registered`);this.bridges.set(e,t)}listDomainBridges(){return[...this.bridges.keys()].sort()}async enqueueLocalChange(t,e){let n=(e||`${t.domain}:${t.entity}:${t.recordId}:${t.type}:${t.id}`).trim();if(!n)throw new Error("idempotencyKey must not be empty");let i=await this.outboxStore.findByIdempotencyKey(n);if(i)return i;let c=new Date().toISOString(),s={outboxId:`outbox_${Date.now()}_${Math.random().toString(36).slice(2)}`,idempotencyKey:n,change:t,retryCount:0,status:"PENDING",createdAt:c,updatedAt:c};return await this.outboxStore.enqueue(s),s}async start(t={}){this.runtimeStateStore.setState({phase:"starting",started:!1,syncing:!1,lastError:null,lastTransitionAt:new Date().toISOString()});try{await this.runtime.start(t),this.runtimeStateStore.setState(e=>({...e,phase:"started",started:!0,syncing:!1,startCount:e.startCount+1,lastError:null,lastTransitionAt:new Date().toISOString()}))}catch(e){throw this.runtimeStateStore.setState({phase:"error",started:!1,syncing:!1,lastError:e instanceof Error?e.message:String(e),lastTransitionAt:new Date().toISOString()}),e}}async stop(){this.stopScheduler(),this.runtimeStateStore.setState({phase:"stopping",started:this.runtime.isStarted(),syncing:!1,lastError:null,lastTransitionAt:new Date().toISOString()});try{await this.runtime.stop(),this.runtimeStateStore.setState(t=>({...t,phase:"stopped",started:!1,syncing:!1,stopCount:t.stopCount+1,lastError:null,lastTransitionAt:new Date().toISOString()}))}catch(t){throw this.runtimeStateStore.setState({phase:"error",started:this.runtime.isStarted(),syncing:!1,lastError:t instanceof Error?t.message:String(t),lastTransitionAt:new Date().toISOString()}),t}}async startSync(t){if(!this.runtime.isStarted())throw new Error("Cannot start sync before runtime is started");this.runtimeStateStore.setState({phase:"syncing",started:!0,syncing:!0,lastError:null,lastTransitionAt:new Date().toISOString()});try{let e=A(t),n=await this.checkpointStore.get(e);if(this.transport){await this.processOutbox(t);let i=await this.transport.pull({scope:t,cursor:n,limit:this.policy.batchSize});await this.applyRemoteChanges(i.changes||[],t),i.nextCursor!==void 0&&await this.checkpointStore.set(e,i.nextCursor)}this.runtimeStateStore.setState(i=>({...i,phase:"started",started:!0,syncing:!1,syncCount:i.syncCount+1,lastError:null,lastTransitionAt:new Date().toISOString()}))}catch(e){throw this.runtimeStateStore.setState({phase:"error",started:this.runtime.isStarted(),syncing:!1,lastError:e instanceof Error?e.message:String(e),lastTransitionAt:new Date().toISOString()}),e}}async stopSync(){this.runtimeStateStore.setState(t=>({...t,phase:this.runtime.isStarted()?"started":"stopped",syncing:!1,lastTransitionAt:new Date().toISOString()}))}isStarted(){return this.runtime.isStarted()}startScheduler(t){if(this.policy.scheduler.mode!=="interval")return;let e=this.policy.scheduler.intervalMs||1e4;this.stopScheduler(),this.schedulerTimer=setInterval(()=>{this.startSync(t).catch(n=>{this.runtimeStateStore.setState(i=>({...i,phase:"error",syncing:!1,lastError:n instanceof Error?n.message:String(n),lastTransitionAt:new Date().toISOString()}))})},e)}stopScheduler(){this.schedulerTimer&&(clearInterval(this.schedulerTimer),this.schedulerTimer=void 0)}async notifyOnline(t){this.policy.scheduler.onlineTrigger!==!1&&await this.startSync(t)}async processOutbox(t){if(!this.transport)return;let e=await this.outboxStore.listPending(this.policy.batchSize);if(e.length===0)return;let n=await this.transport.push({scope:t,outbox:e}),i=new Set((n.applied||[]).map(o=>o.changeId)),c=new Map((n.failed||[]).map(o=>[o.changeId,o])),s=new Set((n.conflicts||[]).map(o=>o.changeId));await this.resolveConflicts(n.conflicts||[],t);for(let o of e){if(i.has(o.change.id)){await this.outboxStore.remove(o.outboxId);continue}let a=c.get(o.change.id);if(a||s.has(o.change.id)){let l=o.retryCount+1;await this.outboxStore.update({...o,retryCount:l,status:l>=this.policy.maxRetry?"FAILED":"PENDING",lastError:(a==null?void 0:a.message)||(s.has(o.change.id)?"SYNC_CONFLICT":o.lastError),updatedAt:new Date().toISOString()})}}}async applyRemoteChanges(t,e){if(!Array.isArray(t)||t.length===0)return;let n=[...t].sort((c,s)=>c.occurredAt.localeCompare(s.occurredAt)),i=new Map;for(let c of n){i.has(c.domain)||i.set(c.domain,[]);let s=i.get(c.domain);s&&s.push(c)}for(let[c,s]of i.entries()){let o=this.bridges.get(c);if(o!=null&&o.applyRemoteChanges&&(await o.applyRemoteChanges(s,e),this.projectionHook))for(let a of s)await this.projectionHook(a,e)}}async resolveConflicts(t,e){var i;if(!((i=this.transport)!=null&&i.resolveConflicts)||t.length===0)return;let n=[];for(let c of t){let s=[...this.conflictResolvers],o=null;for(let a of s){let l=await a(c,{scope:e});if(l){o=l;break}}o||(o=f(c)),n.push(o)}n.length>0&&await this.transport.resolveConflicts({scope:e,resolutions:n})}},S=class{constructor(){this.runtimeBuilder=C.builder();this.options={};this.runtimeBuilder.withDbAdapter(()=>new I)}withPlatformAdapter(t){return this.runtimeBuilder.withPlatformAdapter(t),this}withDbAdapter(t){return this.runtimeBuilder.withDbAdapter(t),this}withHttpAdapter(t){return this.runtimeBuilder.withHttpAdapter(t),this}withSocketAdapter(t){return this.runtimeBuilder.withSocketAdapter(t),this}withLoggerAdapter(t){return this.runtimeBuilder.withLoggerAdapter(t),this}withActivitySink(t){return this.runtimeBuilder.withActivitySink(t),this}withExtension(t,e){return this.runtimeBuilder.withExtension(t,e),this}withPolicy(t){return this.options={...this.options,policy:t},this}withTransport(t){return this.options={...this.options,transport:t},this}withOutboxStore(t){return this.options={...this.options,outboxStore:t},this}withCheckpointStore(t){return this.options={...this.options,checkpointStore:t},this}withConflictResolvers(t){return this.options={...this.options,conflictResolvers:t},this}withProjectionHook(t){return this.options={...this.options,projectionHook:t},this}build(){let t=v({phase:"idle",started:!1,syncing:!1,startCount:0,stopCount:0,syncCount:0,lastError:null,lastTransitionAt:new Date().toISOString()}),e=this.runtimeBuilder.build();return new u(e,t,this.options)}};function q(r={}){let t=u.builder();return r.policy&&t.withPolicy(r.policy),r.transport&&t.withTransport(r.transport),r.outboxStore&&t.withOutboxStore(r.outboxStore),r.checkpointStore&&t.withCheckpointStore(r.checkpointStore),r.conflictResolvers&&t.withConflictResolvers(r.conflictResolvers),r.projectionHook&&t.withProjectionHook(r.projectionHook),t.build()}function G(r,t){r.registerDomainBridge(t)}async function z(r,t,e={}){r.isStarted()||await r.start(e),await r.startSync(t)}async function Y(r){await r.stopSync()}var m=class extends Error{constructor(t,e,n=!1,i){super(e),this.name="OfsyncTransportError",this.code=t,this.retryable=n,this.status=i}};async function R(r){let t=globalThis.crypto;if(!t||!t.subtle)throw new Error("WebCrypto API is not available");let e=new TextEncoder().encode(r),n=await t.subtle.digest("SHA-256",e);return[...new Uint8Array(n)].map(i=>i.toString(16).padStart(2,"0")).join("")}function O(r){let t=String(r.table||""),e=String(r.id||""),n=String(r.changeId||"");return[t,e,n].join("::")}function g(r){return{conflictId:O(r),changeId:String(r.changeId||""),domain:"unknown",entity:String(r.table||""),recordId:String(r.id||""),code:String(r.code||"UNKNOWN_CONFLICT"),message:String(r.message||"Conflict detected"),retryable:!!r.retryable,scope:{tenantId:typeof r.tenantId=="string"?r.tenantId:void 0,branchId:typeof r.branchId=="string"?r.branchId:void 0},details:r}}function P(r){var e;let t=(e=r.branchId)==null?void 0:e.trim();if(!t)throw new m("BRANCH_SCOPE_REQUIRED","Sync scope requires branchId",!1);return t}var b=class{constructor(t){this.options=t}nowIso(){return this.options.nowIso?this.options.nowIso():new Date().toISOString()}async buildHeaders(t){let e={"content-type":"application/json","x-branch-id":P(t)};if(t.tenantId&&(e["x-tenant-id"]=t.tenantId),this.options.getAccessToken){let n=await this.options.getAccessToken();n&&(e.authorization=`Bearer ${n}`)}return e}normalizeUrl(t){return`${this.options.baseUrl.replace(/\/+$/,"")}${t}`}parseFailure(t,e){var o,a,l;let n=e||{},i=((o=n.error)==null?void 0:o.code)||"SYNC_TRANSPORT_ERROR",c=((a=n.error)==null?void 0:a.message)||`Sync transport failed with status ${t}`,s=!!((l=n.error)!=null&&l.retryable);throw new m(i,c,s,t)}async push(t){let e={changes:t.outbox.map(a=>({id:a.change.id,entity:a.change.entity,type:a.change.type,data:{id:a.change.recordId,...a.change.payload},timestamp:a.change.occurredAt}))},n=JSON.stringify(e),i=await R(n),c=await this.buildHeaders(t.scope);c["x-data-checksum"]=i;let s=await this.options.httpAdapter.request({method:"POST",url:this.normalizeUrl("/sync/push"),headers:c,body:e});s.status>=400&&this.parseFailure(s.status,s.data);let o=s.data||{};return{applied:Array.isArray(o.applied)?o.applied:[],failed:Array.isArray(o.failed)?o.failed:[],conflicts:Array.isArray(o.conflicts)?o.conflicts.map(g):[]}}async pull(t){let e=await this.buildHeaders(t.scope),n=t.cursor||this.nowIso(),i=await this.options.httpAdapter.request({method:"GET",url:this.normalizeUrl("/sync/pull"),headers:e,query:{since:n}});i.status>=400&&this.parseFailure(i.status,i.data);let c=i.data||{},s=Array.isArray(c.changes)?c.changes.map(a=>{var l;return{id:String(a.id||""),domain:String(a.domain||"unknown"),entity:String(a.entity||""),type:String(a.type||"UPDATE"),recordId:String(a.recordId||((l=a.record)==null?void 0:l.id)||""),payload:a.record||{},occurredAt:String(a.timestamp||this.nowIso()),scope:t.scope}}):[],o=s.length>0?s[s.length-1].occurredAt:n;return{changes:s,nextCursor:o,conflicts:[]}}async listConflicts(t){let e=await this.buildHeaders(t.scope),n=await this.options.httpAdapter.request({method:"GET",url:this.normalizeUrl("/sync/conflicts"),headers:e});n.status>=400&&this.parseFailure(n.status,n.data);let i=n.data||{};return Array.isArray(i.conflicts)?i.conflicts.map(g):[]}async resolveConflicts(t){var l;let e=await this.listConflicts({scope:t.scope}),n=new Map(e.map(p=>[p.conflictId,p])),i=t.resolutions.map(p=>n.get(p.conflictId)).filter(p=>!!p).map(p=>({table:p.entity,id:p.recordId})),c=await this.buildHeaders(t.scope),s={resolutions:i},o=await this.options.httpAdapter.request({method:"POST",url:this.normalizeUrl("/sync/conflicts/resolve"),headers:c,body:s});o.status>=400&&this.parseFailure(o.status,o.data);let a=Array.isArray((l=o.data)==null?void 0:l.remaining)?o.data.remaining.length:0;return{resolvedCount:Math.max(0,i.length-a)}}};export{d as DEFAULT_SYNC_POLICY,h as InMemoryCheckpointStore,y as InMemoryOutboxStore,_ as OFSYNC_CONTRACT_STAGE,u as OfsyncCore,S as OfsyncCoreBuilder,b as OfsyncHttpTransport,m as OfsyncTransportError,q as createSyncRuntime,f as defaultConflictResolver,G as registerDomainBridge,z as startSync,Y as stopSync};

package/dist/index.js

@@ -0,0 +1 @@
+"use strict";var g=Object.defineProperty;var x=Object.getOwnPropertyDescriptor;var A=Object.getOwnPropertyNames;var R=Object.prototype.hasOwnProperty;var O=(r,t)=>{for(var e in t)g(r,e,{get:t[e],enumerable:!0})},P=(r,t,e,n)=>{if(t&&typeof t=="object"||typeof t=="function")for(let o of A(t))!R.call(r,o)&&o!==e&&g(r,o,{get:()=>t[o],enumerable:!(n=x(t,o))||n.enumerable});return r};var E=r=>P(g({},"__esModule",{value:!0}),r);var U={};O(U,{DEFAULT_SYNC_POLICY:()=>d,InMemoryCheckpointStore:()=>h,InMemoryOutboxStore:()=>y,OFSYNC_CONTRACT_STAGE:()=>k,OfsyncCore:()=>u,OfsyncCoreBuilder:()=>S,OfsyncHttpTransport:()=>C,OfsyncTransportError:()=>m,createSyncRuntime:()=>_,defaultConflictResolver:()=>b,registerDomainBridge:()=>N,startSync:()=>B,stopSync:()=>L});module.exports=E(U);var d={batchSize:200,maxRetry:5,scheduler:{mode:"manual",onlineTrigger:!0},retryBackoff:{strategy:"exponential-jitter",baseDelayMs:500,maxDelayMs:3e4}};var y=class{constructor(){this.rows=new Map}async enqueue(t){this.rows.set(t.outboxId,t)}async listPending(t){return[...this.rows.values()].filter(e=>e.status==="PENDING"||e.status==="FAILED").sort((e,n)=>e.createdAt.localeCompare(n.createdAt)).slice(0,Math.max(0,t))}async findByIdempotencyKey(t){for(let e of this.rows.values())if(e.idempotencyKey===t)return e;return null}async update(t){this.rows.set(t.outboxId,t)}async remove(t){this.rows.delete(t)}};var h=class{constructor(){this.rows=new Map}async get(t){return this.rows.has(t)?this.rows.get(t):null}async set(t,e){this.rows.set(t,e)}};function b(r){return r.code==="VERSION_CONFLICT"?{conflictId:r.conflictId,action:"APPLY_REMOTE"}:r.code==="SCOPE_CONFLICT"?{conflictId:r.conflictId,action:"MANUAL_MERGE"}:{conflictId:r.conflictId,action:"KEEP_LOCAL"}}var k="phase1-runtime-skeleton";var I=require("ofcore"),w=require("ofcore"),f=require("ofcore");function T(r={}){return{...d,...r,scheduler:{...d.scheduler,...r.scheduler||{}},retryBackoff:{...d.retryBackoff,...r.retryBackoff||{}}}}function D(r){return`${r.tenantId||"__standalone__"}::${r.branchId||"__all__"}::${r.deviceId||"__device__"}`}var u=class{constructor(t,e,n={}){this.runtime=t;this.runtimeStateStore=e;this.bridges=new Map;this.runtimeStore=(0,f.asReadonlyStore)(this.runtimeStateStore),this.policy=T(n.policy),this.transport=n.transport,this.outboxStore=n.outboxStore||new y,this.checkpointStore=n.checkpointStore||new h,this.conflictResolvers=n.conflictResolvers||[],this.projectionHook=n.projectionHook}static builder(){return new S}get registry(){return this.runtime.registry}getPolicy(){return this.policy}registerDomainBridge(t){let e=t.domain.trim();if(!e)throw new Error("DomainBridge.domain is required");if(this.bridges.has(e))throw new Error(`DomainBridge for domain "${e}" is already registered`);this.bridges.set(e,t)}listDomainBridges(){return[...this.bridges.keys()].sort()}async enqueueLocalChange(t,e){let n=(e||`${t.domain}:${t.entity}:${t.recordId}:${t.type}:${t.id}`).trim();if(!n)throw new Error("idempotencyKey must not be empty");let o=await this.outboxStore.findByIdempotencyKey(n);if(o)return o;let c=new Date().toISOString(),s={outboxId:`outbox_${Date.now()}_${Math.random().toString(36).slice(2)}`,idempotencyKey:n,change:t,retryCount:0,status:"PENDING",createdAt:c,updatedAt:c};return await this.outboxStore.enqueue(s),s}async start(t={}){this.runtimeStateStore.setState({phase:"starting",started:!1,syncing:!1,lastError:null,lastTransitionAt:new Date().toISOString()});try{await this.runtime.start(t),this.runtimeStateStore.setState(e=>({...e,phase:"started",started:!0,syncing:!1,startCount:e.startCount+1,lastError:null,lastTransitionAt:new Date().toISOString()}))}catch(e){throw this.runtimeStateStore.setState({phase:"error",started:!1,syncing:!1,lastError:e instanceof Error?e.message:String(e),lastTransitionAt:new Date().toISOString()}),e}}async stop(){this.stopScheduler(),this.runtimeStateStore.setState({phase:"stopping",started:this.runtime.isStarted(),syncing:!1,lastError:null,lastTransitionAt:new Date().toISOString()});try{await this.runtime.stop(),this.runtimeStateStore.setState(t=>({...t,phase:"stopped",started:!1,syncing:!1,stopCount:t.stopCount+1,lastError:null,lastTransitionAt:new Date().toISOString()}))}catch(t){throw this.runtimeStateStore.setState({phase:"error",started:this.runtime.isStarted(),syncing:!1,lastError:t instanceof Error?t.message:String(t),lastTransitionAt:new Date().toISOString()}),t}}async startSync(t){if(!this.runtime.isStarted())throw new Error("Cannot start sync before runtime is started");this.runtimeStateStore.setState({phase:"syncing",started:!0,syncing:!0,lastError:null,lastTransitionAt:new Date().toISOString()});try{let e=D(t),n=await this.checkpointStore.get(e);if(this.transport){await this.processOutbox(t);let o=await this.transport.pull({scope:t,cursor:n,limit:this.policy.batchSize});await this.applyRemoteChanges(o.changes||[],t),o.nextCursor!==void 0&&await this.checkpointStore.set(e,o.nextCursor)}this.runtimeStateStore.setState(o=>({...o,phase:"started",started:!0,syncing:!1,syncCount:o.syncCount+1,lastError:null,lastTransitionAt:new Date().toISOString()}))}catch(e){throw this.runtimeStateStore.setState({phase:"error",started:this.runtime.isStarted(),syncing:!1,lastError:e instanceof Error?e.message:String(e),lastTransitionAt:new Date().toISOString()}),e}}async stopSync(){this.runtimeStateStore.setState(t=>({...t,phase:this.runtime.isStarted()?"started":"stopped",syncing:!1,lastTransitionAt:new Date().toISOString()}))}isStarted(){return this.runtime.isStarted()}startScheduler(t){if(this.policy.scheduler.mode!=="interval")return;let e=this.policy.scheduler.intervalMs||1e4;this.stopScheduler(),this.schedulerTimer=setInterval(()=>{this.startSync(t).catch(n=>{this.runtimeStateStore.setState(o=>({...o,phase:"error",syncing:!1,lastError:n instanceof Error?n.message:String(n),lastTransitionAt:new Date().toISOString()}))})},e)}stopScheduler(){this.schedulerTimer&&(clearInterval(this.schedulerTimer),this.schedulerTimer=void 0)}async notifyOnline(t){this.policy.scheduler.onlineTrigger!==!1&&await this.startSync(t)}async processOutbox(t){if(!this.transport)return;let e=await this.outboxStore.listPending(this.policy.batchSize);if(e.length===0)return;let n=await this.transport.push({scope:t,outbox:e}),o=new Set((n.applied||[]).map(i=>i.changeId)),c=new Map((n.failed||[]).map(i=>[i.changeId,i])),s=new Set((n.conflicts||[]).map(i=>i.changeId));await this.resolveConflicts(n.conflicts||[],t);for(let i of e){if(o.has(i.change.id)){await this.outboxStore.remove(i.outboxId);continue}let a=c.get(i.change.id);if(a||s.has(i.change.id)){let l=i.retryCount+1;await this.outboxStore.update({...i,retryCount:l,status:l>=this.policy.maxRetry?"FAILED":"PENDING",lastError:(a==null?void 0:a.message)||(s.has(i.change.id)?"SYNC_CONFLICT":i.lastError),updatedAt:new Date().toISOString()})}}}async applyRemoteChanges(t,e){if(!Array.isArray(t)||t.length===0)return;let n=[...t].sort((c,s)=>c.occurredAt.localeCompare(s.occurredAt)),o=new Map;for(let c of n){o.has(c.domain)||o.set(c.domain,[]);let s=o.get(c.domain);s&&s.push(c)}for(let[c,s]of o.entries()){let i=this.bridges.get(c);if(i!=null&&i.applyRemoteChanges&&(await i.applyRemoteChanges(s,e),this.projectionHook))for(let a of s)await this.projectionHook(a,e)}}async resolveConflicts(t,e){var o;if(!((o=this.transport)!=null&&o.resolveConflicts)||t.length===0)return;let n=[];for(let c of t){let s=[...this.conflictResolvers],i=null;for(let a of s){let l=await a(c,{scope:e});if(l){i=l;break}}i||(i=b(c)),n.push(i)}n.length>0&&await this.transport.resolveConflicts({scope:e,resolutions:n})}},S=class{constructor(){this.runtimeBuilder=I.CoreRuntime.builder();this.options={};this.runtimeBuilder.withDbAdapter(()=>new w.InMemoryDbAdapter)}withPlatformAdapter(t){return this.runtimeBuilder.withPlatformAdapter(t),this}withDbAdapter(t){return this.runtimeBuilder.withDbAdapter(t),this}withHttpAdapter(t){return this.runtimeBuilder.withHttpAdapter(t),this}withSocketAdapter(t){return this.runtimeBuilder.withSocketAdapter(t),this}withLoggerAdapter(t){return this.runtimeBuilder.withLoggerAdapter(t),this}withActivitySink(t){return this.runtimeBuilder.withActivitySink(t),this}withExtension(t,e){return this.runtimeBuilder.withExtension(t,e),this}withPolicy(t){return this.options={...this.options,policy:t},this}withTransport(t){return this.options={...this.options,transport:t},this}withOutboxStore(t){return this.options={...this.options,outboxStore:t},this}withCheckpointStore(t){return this.options={...this.options,checkpointStore:t},this}withConflictResolvers(t){return this.options={...this.options,conflictResolvers:t},this}withProjectionHook(t){return this.options={...this.options,projectionHook:t},this}build(){let t=(0,f.createStore)({phase:"idle",started:!1,syncing:!1,startCount:0,stopCount:0,syncCount:0,lastError:null,lastTransitionAt:new Date().toISOString()}),e=this.runtimeBuilder.build();return new u(e,t,this.options)}};function _(r={}){let t=u.builder();return r.policy&&t.withPolicy(r.policy),r.transport&&t.withTransport(r.transport),r.outboxStore&&t.withOutboxStore(r.outboxStore),r.checkpointStore&&t.withCheckpointStore(r.checkpointStore),r.conflictResolvers&&t.withConflictResolvers(r.conflictResolvers),r.projectionHook&&t.withProjectionHook(r.projectionHook),t.build()}function N(r,t){r.registerDomainBridge(t)}async function B(r,t,e={}){r.isStarted()||await r.start(e),await r.startSync(t)}async function L(r){await r.stopSync()}var m=class extends Error{constructor(t,e,n=!1,o){super(e),this.name="OfsyncTransportError",this.code=t,this.retryable=n,this.status=o}};async function M(r){let t=globalThis.crypto;if(!t||!t.subtle)throw new Error("WebCrypto API is not available");let e=new TextEncoder().encode(r),n=await t.subtle.digest("SHA-256",e);return[...new Uint8Array(n)].map(o=>o.toString(16).padStart(2,"0")).join("")}function H(r){let t=String(r.table||""),e=String(r.id||""),n=String(r.changeId||"");return[t,e,n].join("::")}function v(r){return{conflictId:H(r),changeId:String(r.changeId||""),domain:"unknown",entity:String(r.table||""),recordId:String(r.id||""),code:String(r.code||"UNKNOWN_CONFLICT"),message:String(r.message||"Conflict detected"),retryable:!!r.retryable,scope:{tenantId:typeof r.tenantId=="string"?r.tenantId:void 0,branchId:typeof r.branchId=="string"?r.branchId:void 0},details:r}}function F(r){var e;let t=(e=r.branchId)==null?void 0:e.trim();if(!t)throw new m("BRANCH_SCOPE_REQUIRED","Sync scope requires branchId",!1);return t}var C=class{constructor(t){this.options=t}nowIso(){return this.options.nowIso?this.options.nowIso():new Date().toISOString()}async buildHeaders(t){let e={"content-type":"application/json","x-branch-id":F(t)};if(t.tenantId&&(e["x-tenant-id"]=t.tenantId),this.options.getAccessToken){let n=await this.options.getAccessToken();n&&(e.authorization=`Bearer ${n}`)}return e}normalizeUrl(t){return`${this.options.baseUrl.replace(/\/+$/,"")}${t}`}parseFailure(t,e){var i,a,l;let n=e||{},o=((i=n.error)==null?void 0:i.code)||"SYNC_TRANSPORT_ERROR",c=((a=n.error)==null?void 0:a.message)||`Sync transport failed with status ${t}`,s=!!((l=n.error)!=null&&l.retryable);throw new m(o,c,s,t)}async push(t){let e={changes:t.outbox.map(a=>({id:a.change.id,entity:a.change.entity,type:a.change.type,data:{id:a.change.recordId,...a.change.payload},timestamp:a.change.occurredAt}))},n=JSON.stringify(e),o=await M(n),c=await this.buildHeaders(t.scope);c["x-data-checksum"]=o;let s=await this.options.httpAdapter.request({method:"POST",url:this.normalizeUrl("/sync/push"),headers:c,body:e});s.status>=400&&this.parseFailure(s.status,s.data);let i=s.data||{};return{applied:Array.isArray(i.applied)?i.applied:[],failed:Array.isArray(i.failed)?i.failed:[],conflicts:Array.isArray(i.conflicts)?i.conflicts.map(v):[]}}async pull(t){let e=await this.buildHeaders(t.scope),n=t.cursor||this.nowIso(),o=await this.options.httpAdapter.request({method:"GET",url:this.normalizeUrl("/sync/pull"),headers:e,query:{since:n}});o.status>=400&&this.parseFailure(o.status,o.data);let c=o.data||{},s=Array.isArray(c.changes)?c.changes.map(a=>{var l;return{id:String(a.id||""),domain:String(a.domain||"unknown"),entity:String(a.entity||""),type:String(a.type||"UPDATE"),recordId:String(a.recordId||((l=a.record)==null?void 0:l.id)||""),payload:a.record||{},occurredAt:String(a.timestamp||this.nowIso()),scope:t.scope}}):[],i=s.length>0?s[s.length-1].occurredAt:n;return{changes:s,nextCursor:i,conflicts:[]}}async listConflicts(t){let e=await this.buildHeaders(t.scope),n=await this.options.httpAdapter.request({method:"GET",url:this.normalizeUrl("/sync/conflicts"),headers:e});n.status>=400&&this.parseFailure(n.status,n.data);let o=n.data||{};return Array.isArray(o.conflicts)?o.conflicts.map(v):[]}async resolveConflicts(t){var l;let e=await this.listConflicts({scope:t.scope}),n=new Map(e.map(p=>[p.conflictId,p])),o=t.resolutions.map(p=>n.get(p.conflictId)).filter(p=>!!p).map(p=>({table:p.entity,id:p.recordId})),c=await this.buildHeaders(t.scope),s={resolutions:o},i=await this.options.httpAdapter.request({method:"POST",url:this.normalizeUrl("/sync/conflicts/resolve"),headers:c,body:s});i.status>=400&&this.parseFailure(i.status,i.data);let a=Array.isArray((l=i.data)==null?void 0:l.remaining)?i.data.remaining.length:0;return{resolvedCount:Math.max(0,o.length-a)}}};

package/dist/runtime/ContractStage.d.ts

@@ -0,0 +1,2 @@
+export type OfsyncContractStage = 'phase1-runtime-skeleton';
+export declare const OFSYNC_CONTRACT_STAGE: OfsyncContractStage;

package/dist/services/ConflictResolver.d.ts

@@ -0,0 +1,11 @@
+import type { ConflictItem, SyncScope } from '../contracts/SyncContract';
+export type ConflictResolutionAction = 'APPLY_REMOTE' | 'KEEP_LOCAL' | 'MANUAL_MERGE';
+export interface ConflictResolutionDecision {
+    conflictId: string;
+    action: ConflictResolutionAction;
+}
+export interface ConflictResolverContext {
+    scope: SyncScope;
+}
+export type ConflictResolver = (conflict: ConflictItem, context: ConflictResolverContext) => Promise<ConflictResolutionDecision | null> | ConflictResolutionDecision | null;
+export declare function defaultConflictResolver(conflict: ConflictItem): ConflictResolutionDecision;

package/dist/services/DomainBridge.d.ts

@@ -0,0 +1,6 @@
+import type { SyncChange, SyncScope } from '../contracts/SyncContract';
+export interface DomainBridge {
+    domain: string;
+    collectLocalChanges?: (scope: SyncScope) => Promise<SyncChange[]>;
+    applyRemoteChanges?: (changes: SyncChange[], scope: SyncScope) => Promise<void>;
+}

package/dist/services/InMemoryCheckpointStore.d.ts

@@ -0,0 +1,9 @@
+export interface CheckpointStore {
+    get(scopeKey: string): Promise<string | null>;
+    set(scopeKey: string, value: string | null): Promise<void>;
+}
+export declare class InMemoryCheckpointStore implements CheckpointStore {
+    private readonly rows;
+    get(scopeKey: string): Promise<string | null>;
+    set(scopeKey: string, value: string | null): Promise<void>;
+}

package/dist/services/InMemoryOutboxStore.d.ts

@@ -0,0 +1,16 @@
+import type { OutboxItem } from '../contracts/SyncContract';
+export interface OutboxStore {
+    enqueue(item: OutboxItem): Promise<void>;
+    listPending(limit: number): Promise<OutboxItem[]>;
+    findByIdempotencyKey(idempotencyKey: string): Promise<OutboxItem | null>;
+    update(item: OutboxItem): Promise<void>;
+    remove(outboxId: string): Promise<void>;
+}
+export declare class InMemoryOutboxStore implements OutboxStore {
+    private readonly rows;
+    enqueue(item: OutboxItem): Promise<void>;
+    listPending(limit: number): Promise<OutboxItem[]>;
+    findByIdempotencyKey(idempotencyKey: string): Promise<OutboxItem | null>;
+    update(item: OutboxItem): Promise<void>;
+    remove(outboxId: string): Promise<void>;
+}

package/dist/services/SyncTransport.d.ts

@@ -0,0 +1,42 @@
+import type { ConflictItem, OutboxItem, SyncChange, SyncScope } from '../contracts/SyncContract';
+export interface SyncPushResult {
+    applied: Array<{
+        changeId: string;
+        status: 'OK' | 'ALREADY_PROCESSED';
+    }>;
+    failed: Array<{
+        changeId: string;
+        code: string;
+        message: string;
+        retryable: boolean;
+    }>;
+    conflicts: ConflictItem[];
+}
+export interface SyncPullResult {
+    changes: SyncChange[];
+    nextCursor: string | null;
+    conflicts?: ConflictItem[];
+}
+export interface SyncTransport {
+    push(params: {
+        scope: SyncScope;
+        outbox: OutboxItem[];
+    }): Promise<SyncPushResult>;
+    pull(params: {
+        scope: SyncScope;
+        cursor: string | null;
+        limit: number;
+    }): Promise<SyncPullResult>;
+    listConflicts?(params: {
+        scope: SyncScope;
+    }): Promise<ConflictItem[]>;
+    resolveConflicts?(params: {
+        scope: SyncScope;
+        resolutions: Array<{
+            conflictId: string;
+            action: 'APPLY_REMOTE' | 'KEEP_LOCAL' | 'MANUAL_MERGE';
+        }>;
+    }): Promise<{
+        resolvedCount: number;
+    }>;
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "ofsync-shared-core",
+  "version": "0.2.0-alpha.0",
+  "private": false,
+  "description": "Host-side offline-first sync orchestration core for multi-domain of* apps.",
+  "author": {
+    "name": "Agus Made",
+    "email": "krisnaparta@gmail.com"
+  },
+  "main": "dist/index.js",
+  "module": "dist/index.esm.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.esm.js",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
+    "build": "npm run clean && tsc -p tsconfig.build.json && node esbuild.config.js",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "NODE_PATH=.. npm run build && NODE_PATH=.. node --test ./tests/*.test.js",
+    "verify:contract": "node ./scripts/verify-surface.js",
+    "verify:surface": "node ./scripts/verify-surface.js",
+    "verify:boundary": "node ./scripts/verify-boundary-imports.js",
+    "verify:no-env": "node ./scripts/verify-no-env-coupling.js",
+    "ci:check": "npm run typecheck && npm run verify:contract && npm run verify:boundary && npm run verify:no-env && npm run test",
+    "prepublishOnly": "npm run ci:check",
+    "prepack": "npm run build",
+    "bundle": "node esbuild.config.js"
+  },
+  "dependencies": {
+    "ofcore": "0.1.0-alpha.0"
+  },
+  "devDependencies": {
+    "esbuild": "^0.25.11",
+    "typescript": "^5.9.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}