@super-line/core 0.4.0 → 0.5.0

package/dist/index.d.cts

@@ -418,6 +418,37 @@ type InspectorEvent = {
     ok: boolean;
     output?: unknown;
     error?: MessageError;
+} | {
+    type: 'store.write';
+    store: string;
+    id: string;
+    origin: string;
+    connId?: string;
+    data: unknown;
+} | {
+    type: 'store.grant';
+    store: string;
+    id: string;
+    principal: string;
+    perms: {
+        read: boolean;
+        write: boolean;
+    };
+} | {
+    type: 'store.revoke';
+    store: string;
+    id: string;
+    principal: string;
+} | {
+    type: 'store.subscribe';
+    connId: string;
+    store: string;
+    id: string;
+} | {
+    type: 'store.unsubscribe';
+    connId: string;
+    store: string;
+    id: string;
 };
 /**
  * The fixed, library-owned contract describing the inspector surface. Identical for every
@@ -509,7 +540,32 @@ interface PingFrame {
 interface PongFrame {
     t: 'pong';
 }
-type ClientFrame = ReqFrame | SubFrame | UnsubFrame | SResFrame | SErrFrame | PingFrame | PongFrame;
+interface SOpenFrame {
+    t: 'sopen';
+    i: number;
+    n: string;
+    id: string;
+}
+interface SCloseFrame {
+    t: 'sclose';
+    n: string;
+    id: string;
+}
+interface SWriteFrame {
+    t: 'swr';
+    i: number;
+    n: string;
+    id: string;
+    u: unknown;
+    o: string;
+}
+interface SReadFrame {
+    t: 'srd';
+    i: number;
+    n: string;
+    id: string;
+}
+type ClientFrame = ReqFrame | SubFrame | UnsubFrame | SResFrame | SErrFrame | SOpenFrame | SCloseFrame | SWriteFrame | SReadFrame | PingFrame | PongFrame;
 interface ResFrame {
     t: 'res';
     i: number;
@@ -539,9 +595,110 @@ interface SReqFrame {
     m: string;
     d: unknown;
 }
-type ServerFrame = ResFrame | ErrFrame | EvtFrame | PubFrame | SReqFrame | PingFrame | PongFrame;
+interface SChangeFrame {
+    t: 'sch';
+    n: string;
+    id: string;
+    u: unknown;
+    o: string;
+    nd?: string;
+}
+type ServerFrame = ResFrame | ErrFrame | EvtFrame | PubFrame | SReqFrame | SChangeFrame | PingFrame | PongFrame;
 type Frame = ClientFrame | ServerFrame;
 
+/**
+ * Store — super-line's pluggable persisted-state seam.
+ *
+ * A Store persists Resources (`{ id, accessRules, data }`) and defines a single consistency model
+ * (how a write mutates `data`). It ships as a pair, like a transport: a {@link ServerStore}
+ * (persistence + change-notify) and a {@link ClientStore} (a reactive local replica). super-line core
+ * relays opaque {@link StoreChange}s between the halves and enforces access — it never parses `update`.
+ * "One plumbing, two consistency models": a last-writer-wins memory store and a merging CRDT store are
+ * siblings behind this interface.
+ */
+type Awaitable<T> = T | Promise<T>;
+/** The ACL identity a Resource's access is keyed by (`identify(conn) ?? conn.id`). */
+type Principal = string;
+/** Per-principal capabilities on a Resource. */
+interface Perms {
+    read: boolean;
+    write: boolean;
+}
+/** A Resource's access map: which {@link Principal} may read/write. Server-authoritative, deny-by-default. */
+type AccessRules = Record<Principal, Perms>;
+/** The unit a Store persists. `data` is opaque to core (a CRDT doc for a merging store, plain JSON for LWW). */
+interface Resource<T = unknown> {
+    id: string;
+    accessRules: AccessRules;
+    data: T;
+}
+/**
+ * What a Store emits when a Resource mutates — and the symmetric shape a write carries IN.
+ * `update` is a store-DEFINED opaque payload (a CRDT delta, or a full JSON value for last-writer-wins);
+ * core relays it without parsing (base64 it if it's bytes under the JSON serializer). `origin` is the
+ * per-writer id used for echo-break — never the {@link Principal}, never the CRDT actor id.
+ */
+interface StoreChange {
+    id: string;
+    update: unknown;
+    origin: string;
+}
+/**
+ * The server half of a Store pair: persistence + the consistency model + change-notification.
+ * It does NOT enforce access (core does) and does NOT touch the wire. `apply` interprets a
+ * {@link StoreChange} per its consistency model (LWW replace vs CRDT merge); every applied mutation —
+ * client write, server co-write, or relayed remote change — must surface through {@link ServerStore.onChange},
+ * which is core's single fan-out source.
+ */
+interface ServerStore {
+    /**
+     * How cross-node sync happens: `relay` (core relays Changes over the adapter; each node a replica)
+     * or `self` (the store owns a shared backend and core fans only to local subscribers).
+     */
+    readonly clustering: 'relay' | 'self';
+    /** Current snapshot of a Resource (for catch-up on subscribe), or undefined if absent. */
+    read(id: string): Awaitable<Resource | undefined>;
+    /** Create a Resource with initial data + access rules (server-authoritative). */
+    create(id: string, data: unknown, accessRules: AccessRules): Awaitable<void>;
+    /** Apply an inbound Change — replace (LWW) or merge (CRDT), the store's choice. */
+    apply(change: StoreChange): Awaitable<void>;
+    /** Replace a Resource's access rules. */
+    setAccess(id: string, accessRules: AccessRules): Awaitable<void>;
+    /** Remove a Resource. */
+    delete(id: string): Awaitable<void>;
+    /** All Resource ids in this store (core ACL-filters before returning ids to a client). */
+    list(): Awaitable<string[]>;
+    /** Subscribe to every applied mutation — the single fan-out source. Returns an unsubscribe fn. */
+    onChange(cb: (change: StoreChange) => void): () => void;
+    /** Release any resources held by the store. */
+    close?(): Awaitable<void>;
+}
+/**
+ * The client half of a Store pair: a reactive local replica per opened Resource. A last-writer-wins
+ * client wraps a plain value; a CRDT client wraps super-store's `StoreValue` and merges deltas.
+ */
+interface ClientStore {
+    /** This client's per-writer id, stamped as {@link StoreChange.origin} for echo-break. */
+    readonly origin: string;
+    /** Open a reactive replica for one Resource. */
+    open(id: string): ResourceReplica;
+    /** Release any resources held by the store. */
+    close?(): void;
+}
+/**
+ * A reactive handle over one opened Resource (mirrors super-store's `StoreValue` surface).
+ * `set`/`update` return the {@link StoreChange} to send up (null on a no-op); `applyRemote` merges an
+ * inbound Change (own-origin merges are idempotent / no-ops); `seed` hydrates the catch-up snapshot.
+ */
+interface ResourceReplica {
+    getSnapshot(): unknown;
+    subscribe(cb: () => void): () => void;
+    set(data: unknown): StoreChange | null;
+    update(partial: unknown): StoreChange | null;
+    applyRemote(change: StoreChange): void;
+    seed(snapshot: unknown): void;
+}
+
 /**
  * The client↔server transport seam. A transport moves opaque encoded bytes over a
  * LOGICAL connection and hides all physical churn (reconnects, SSE's dual channel,
@@ -620,4 +777,4 @@ interface ClientTransport {
     }): RawConn;
 }
 
-export { type Adapter, type AnyData, type AuthOutcome, type ClientFrame, type ClientInput, type ClientTransport, type ConnDescriptor, type ConnView, type Contract, type DataOf, type Directional, type EmitData, type ErrFrame, type ErrorCode, type EventData, type Events, type EvtFrame, type Frame, type Handshake, INSPECTOR_ROLE, INSPECTOR_SUBPROTOCOL, type InferIn, type InferOut, type InspectedContract, type InspectedDirectional, type InspectedMessage, InspectorContract, type InspectorEvent, type MessageFlavor, type NodeStat, type NodeView, type Output, PROTOCOL, type PingFrame, type PongFrame, type PresenceStore, type PubFrame, type RawConn, type ReqFrame, type RequestDef, type Requests, type ResFrame, type RoleBlock, type RoleOf, type RoleRequests, type RoleTopics, type SErrFrame, type SReqFrame, type SResFrame, type Schema, type SchemaConverter, type Serializer, type ServerEntry, type ServerFrame, type ServerInput, type ServerMessageDef, type ServerMessages, type ServerRequestDef, type ServerRequests, type ServerTransport, type SharedEvents, type SharedRequests, type SharedServerRequests, type SharedTopics, type SubFrame, SuperLineError, type SuperLineErrorCode, type Topics, type UnsubFrame, classifyContract, defineContract, jsonSerializer, validate, validateSync };
+export { type AccessRules, type Adapter, type AnyData, type AuthOutcome, type ClientFrame, type ClientInput, type ClientStore, type ClientTransport, type ConnDescriptor, type ConnView, type Contract, type DataOf, type Directional, type EmitData, type ErrFrame, type ErrorCode, type EventData, type Events, type EvtFrame, type Frame, type Handshake, INSPECTOR_ROLE, INSPECTOR_SUBPROTOCOL, type InferIn, type InferOut, type InspectedContract, type InspectedDirectional, type InspectedMessage, InspectorContract, type InspectorEvent, type MessageFlavor, type NodeStat, type NodeView, type Output, PROTOCOL, type Perms, type PingFrame, type PongFrame, type PresenceStore, type Principal, type PubFrame, type RawConn, type ReqFrame, type RequestDef, type Requests, type ResFrame, type Resource, type ResourceReplica, type RoleBlock, type RoleOf, type RoleRequests, type RoleTopics, type SChangeFrame, type SCloseFrame, type SErrFrame, type SOpenFrame, type SReadFrame, type SReqFrame, type SResFrame, type SWriteFrame, type Schema, type SchemaConverter, type Serializer, type ServerEntry, type ServerFrame, type ServerInput, type ServerMessageDef, type ServerMessages, type ServerRequestDef, type ServerRequests, type ServerStore, type ServerTransport, type SharedEvents, type SharedRequests, type SharedServerRequests, type SharedTopics, type StoreChange, type SubFrame, SuperLineError, type SuperLineErrorCode, type Topics, type UnsubFrame, classifyContract, defineContract, jsonSerializer, validate, validateSync };

package/dist/index.d.ts

@@ -418,6 +418,37 @@ type InspectorEvent = {
     ok: boolean;
     output?: unknown;
     error?: MessageError;
+} | {
+    type: 'store.write';
+    store: string;
+    id: string;
+    origin: string;
+    connId?: string;
+    data: unknown;
+} | {
+    type: 'store.grant';
+    store: string;
+    id: string;
+    principal: string;
+    perms: {
+        read: boolean;
+        write: boolean;
+    };
+} | {
+    type: 'store.revoke';
+    store: string;
+    id: string;
+    principal: string;
+} | {
+    type: 'store.subscribe';
+    connId: string;
+    store: string;
+    id: string;
+} | {
+    type: 'store.unsubscribe';
+    connId: string;
+    store: string;
+    id: string;
 };
 /**
  * The fixed, library-owned contract describing the inspector surface. Identical for every
@@ -509,7 +540,32 @@ interface PingFrame {
 interface PongFrame {
     t: 'pong';
 }
-type ClientFrame = ReqFrame | SubFrame | UnsubFrame | SResFrame | SErrFrame | PingFrame | PongFrame;
+interface SOpenFrame {
+    t: 'sopen';
+    i: number;
+    n: string;
+    id: string;
+}
+interface SCloseFrame {
+    t: 'sclose';
+    n: string;
+    id: string;
+}
+interface SWriteFrame {
+    t: 'swr';
+    i: number;
+    n: string;
+    id: string;
+    u: unknown;
+    o: string;
+}
+interface SReadFrame {
+    t: 'srd';
+    i: number;
+    n: string;
+    id: string;
+}
+type ClientFrame = ReqFrame | SubFrame | UnsubFrame | SResFrame | SErrFrame | SOpenFrame | SCloseFrame | SWriteFrame | SReadFrame | PingFrame | PongFrame;
 interface ResFrame {
     t: 'res';
     i: number;
@@ -539,9 +595,110 @@ interface SReqFrame {
     m: string;
     d: unknown;
 }
-type ServerFrame = ResFrame | ErrFrame | EvtFrame | PubFrame | SReqFrame | PingFrame | PongFrame;
+interface SChangeFrame {
+    t: 'sch';
+    n: string;
+    id: string;
+    u: unknown;
+    o: string;
+    nd?: string;
+}
+type ServerFrame = ResFrame | ErrFrame | EvtFrame | PubFrame | SReqFrame | SChangeFrame | PingFrame | PongFrame;
 type Frame = ClientFrame | ServerFrame;
 
+/**
+ * Store — super-line's pluggable persisted-state seam.
+ *
+ * A Store persists Resources (`{ id, accessRules, data }`) and defines a single consistency model
+ * (how a write mutates `data`). It ships as a pair, like a transport: a {@link ServerStore}
+ * (persistence + change-notify) and a {@link ClientStore} (a reactive local replica). super-line core
+ * relays opaque {@link StoreChange}s between the halves and enforces access — it never parses `update`.
+ * "One plumbing, two consistency models": a last-writer-wins memory store and a merging CRDT store are
+ * siblings behind this interface.
+ */
+type Awaitable<T> = T | Promise<T>;
+/** The ACL identity a Resource's access is keyed by (`identify(conn) ?? conn.id`). */
+type Principal = string;
+/** Per-principal capabilities on a Resource. */
+interface Perms {
+    read: boolean;
+    write: boolean;
+}
+/** A Resource's access map: which {@link Principal} may read/write. Server-authoritative, deny-by-default. */
+type AccessRules = Record<Principal, Perms>;
+/** The unit a Store persists. `data` is opaque to core (a CRDT doc for a merging store, plain JSON for LWW). */
+interface Resource<T = unknown> {
+    id: string;
+    accessRules: AccessRules;
+    data: T;
+}
+/**
+ * What a Store emits when a Resource mutates — and the symmetric shape a write carries IN.
+ * `update` is a store-DEFINED opaque payload (a CRDT delta, or a full JSON value for last-writer-wins);
+ * core relays it without parsing (base64 it if it's bytes under the JSON serializer). `origin` is the
+ * per-writer id used for echo-break — never the {@link Principal}, never the CRDT actor id.
+ */
+interface StoreChange {
+    id: string;
+    update: unknown;
+    origin: string;
+}
+/**
+ * The server half of a Store pair: persistence + the consistency model + change-notification.
+ * It does NOT enforce access (core does) and does NOT touch the wire. `apply` interprets a
+ * {@link StoreChange} per its consistency model (LWW replace vs CRDT merge); every applied mutation —
+ * client write, server co-write, or relayed remote change — must surface through {@link ServerStore.onChange},
+ * which is core's single fan-out source.
+ */
+interface ServerStore {
+    /**
+     * How cross-node sync happens: `relay` (core relays Changes over the adapter; each node a replica)
+     * or `self` (the store owns a shared backend and core fans only to local subscribers).
+     */
+    readonly clustering: 'relay' | 'self';
+    /** Current snapshot of a Resource (for catch-up on subscribe), or undefined if absent. */
+    read(id: string): Awaitable<Resource | undefined>;
+    /** Create a Resource with initial data + access rules (server-authoritative). */
+    create(id: string, data: unknown, accessRules: AccessRules): Awaitable<void>;
+    /** Apply an inbound Change — replace (LWW) or merge (CRDT), the store's choice. */
+    apply(change: StoreChange): Awaitable<void>;
+    /** Replace a Resource's access rules. */
+    setAccess(id: string, accessRules: AccessRules): Awaitable<void>;
+    /** Remove a Resource. */
+    delete(id: string): Awaitable<void>;
+    /** All Resource ids in this store (core ACL-filters before returning ids to a client). */
+    list(): Awaitable<string[]>;
+    /** Subscribe to every applied mutation — the single fan-out source. Returns an unsubscribe fn. */
+    onChange(cb: (change: StoreChange) => void): () => void;
+    /** Release any resources held by the store. */
+    close?(): Awaitable<void>;
+}
+/**
+ * The client half of a Store pair: a reactive local replica per opened Resource. A last-writer-wins
+ * client wraps a plain value; a CRDT client wraps super-store's `StoreValue` and merges deltas.
+ */
+interface ClientStore {
+    /** This client's per-writer id, stamped as {@link StoreChange.origin} for echo-break. */
+    readonly origin: string;
+    /** Open a reactive replica for one Resource. */
+    open(id: string): ResourceReplica;
+    /** Release any resources held by the store. */
+    close?(): void;
+}
+/**
+ * A reactive handle over one opened Resource (mirrors super-store's `StoreValue` surface).
+ * `set`/`update` return the {@link StoreChange} to send up (null on a no-op); `applyRemote` merges an
+ * inbound Change (own-origin merges are idempotent / no-ops); `seed` hydrates the catch-up snapshot.
+ */
+interface ResourceReplica {
+    getSnapshot(): unknown;
+    subscribe(cb: () => void): () => void;
+    set(data: unknown): StoreChange | null;
+    update(partial: unknown): StoreChange | null;
+    applyRemote(change: StoreChange): void;
+    seed(snapshot: unknown): void;
+}
+
 /**
  * The client↔server transport seam. A transport moves opaque encoded bytes over a
  * LOGICAL connection and hides all physical churn (reconnects, SSE's dual channel,
@@ -620,4 +777,4 @@ interface ClientTransport {
     }): RawConn;
 }
 
-export { type Adapter, type AnyData, type AuthOutcome, type ClientFrame, type ClientInput, type ClientTransport, type ConnDescriptor, type ConnView, type Contract, type DataOf, type Directional, type EmitData, type ErrFrame, type ErrorCode, type EventData, type Events, type EvtFrame, type Frame, type Handshake, INSPECTOR_ROLE, INSPECTOR_SUBPROTOCOL, type InferIn, type InferOut, type InspectedContract, type InspectedDirectional, type InspectedMessage, InspectorContract, type InspectorEvent, type MessageFlavor, type NodeStat, type NodeView, type Output, PROTOCOL, type PingFrame, type PongFrame, type PresenceStore, type PubFrame, type RawConn, type ReqFrame, type RequestDef, type Requests, type ResFrame, type RoleBlock, type RoleOf, type RoleRequests, type RoleTopics, type SErrFrame, type SReqFrame, type SResFrame, type Schema, type SchemaConverter, type Serializer, type ServerEntry, type ServerFrame, type ServerInput, type ServerMessageDef, type ServerMessages, type ServerRequestDef, type ServerRequests, type ServerTransport, type SharedEvents, type SharedRequests, type SharedServerRequests, type SharedTopics, type SubFrame, SuperLineError, type SuperLineErrorCode, type Topics, type UnsubFrame, classifyContract, defineContract, jsonSerializer, validate, validateSync };
+export { type AccessRules, type Adapter, type AnyData, type AuthOutcome, type ClientFrame, type ClientInput, type ClientStore, type ClientTransport, type ConnDescriptor, type ConnView, type Contract, type DataOf, type Directional, type EmitData, type ErrFrame, type ErrorCode, type EventData, type Events, type EvtFrame, type Frame, type Handshake, INSPECTOR_ROLE, INSPECTOR_SUBPROTOCOL, type InferIn, type InferOut, type InspectedContract, type InspectedDirectional, type InspectedMessage, InspectorContract, type InspectorEvent, type MessageFlavor, type NodeStat, type NodeView, type Output, PROTOCOL, type Perms, type PingFrame, type PongFrame, type PresenceStore, type Principal, type PubFrame, type RawConn, type ReqFrame, type RequestDef, type Requests, type ResFrame, type Resource, type ResourceReplica, type RoleBlock, type RoleOf, type RoleRequests, type RoleTopics, type SChangeFrame, type SCloseFrame, type SErrFrame, type SOpenFrame, type SReadFrame, type SReqFrame, type SResFrame, type SWriteFrame, type Schema, type SchemaConverter, type Serializer, type ServerEntry, type ServerFrame, type ServerInput, type ServerMessageDef, type ServerMessages, type ServerRequestDef, type ServerRequests, type ServerStore, type ServerTransport, type SharedEvents, type SharedRequests, type SharedServerRequests, type SharedTopics, type StoreChange, type SubFrame, SuperLineError, type SuperLineErrorCode, type Topics, type UnsubFrame, classifyContract, defineContract, jsonSerializer, validate, validateSync };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@super-line/core",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "type": "module",
   "description": "Shared contract, validation, wire protocol and errors for super-line.",
   "license": "MIT",