@agentshouse/mdruntime-families 0.1.0-cf706e877ebe3 → 0.1.0-cf730a0a343ec

package/README.md

@@ -40,12 +40,17 @@ compare for equality, a list for membership, and the suffixes `_gt`, `_gte`,
 `lt`, `gt`, `lte`, `gte`, `in`, `nin`, `or` and `and`. A field the Room schema
 declares a reference, at any depth, holds the referenced record's id; `id` and
 a reference compare only for equality and membership. Pages and totals are
-counted over every matching record. react-admin's `update` writes the fields
+counted over every matching record, and a page reads only its own window of
+the Room; a list asked for without a page reads every record, window by
+window. react-admin's `update` writes the fields
 that differ from `previousData`, based on it, so the Save of a field another
 writer changed meanwhile is refused; Refine's `update` and either `updateMany`
-compare with the stored record. A list stays current: react-admin's queries of
-a resource are invalidated, and Refine's live mode refetches, when a document
-of the resource changes.
+compare with the stored record. A Room the Runtime holds locked is left out of
+every list, and a read or a write of a record in it rejects with the code
+`room-locked`. A list stays current: react-admin's queries of a resource are
+invalidated, and Refine's live mode refetches, when a record a page or a read
+shows changes, a record a filter names starts or stops matching it, a page's
+total changes, or a Room the list left out as locked unlocks.
 
 ## License
 

package/dist/mdruntime/adapter.d.ts

@@ -0,0 +1,530 @@
+import type { ModelResult } from './model.js';
+import type { Open } from './open.js';
+import type { ChangeBatch } from './change.js';
+export type Authorization = object;
+export type MdModelIdentity = {
+    identity: string;
+    version: string;
+};
+export type TypedSelection = {
+    roots: readonly string[];
+};
+export type OperationScopes = {
+    write: readonly string[];
+    delete: readonly string[];
+};
+export type ReplicaAdmission = {
+    selection: string;
+    admission: Open<'admitted' | 'unavailable'>;
+    offline: Open<'locked' | 'open'>;
+};
+export type DiscoveredRoom = {
+    name: string;
+    locator: string;
+    handle: string;
+    roomVersion: string;
+    operations: OperationScopes;
+    replica: ReplicaAdmission;
+    typedSelection?: TypedSelection;
+    providerOwnedPaths: readonly string[];
+};
+export type Capability = {
+    name: string;
+    limits?: readonly ProviderLimit[];
+    actions?: readonly ActionDeclaration[];
+    conversationAgents?: ConversationAgents;
+};
+export type ConversationAgents = {
+    locator: string;
+    type: string;
+    identity: string;
+    name: string;
+    retired?: string;
+};
+export type ListedConversation = {
+    conversation: string;
+    agent: string;
+    name: string;
+    created: string;
+    finished: string | null;
+    outcome: string | null;
+    waiting: boolean;
+};
+export type ConversationAction = 'conversation.create' | 'conversation.send' | 'conversation.answer' | 'conversation.interrupt' | 'conversation.kill' | 'conversation.cancel' | 'conversation.delete' | 'conversation.history';
+export type ConversationMessage = {
+    identity: string;
+    turn: string;
+    text: string;
+    message: unknown;
+};
+export type AcceptedMessage = ConversationMessage & {
+    position: string;
+};
+export type ConversationHistoryRequest = {
+    conversations: readonly {
+        conversation: string;
+        after?: string;
+    }[];
+};
+export type ConversationHistoryPage = {
+    conversation: string;
+    messages: readonly AcceptedMessage[];
+    next?: string;
+};
+export type ConversationHistories = {
+    histories: readonly ConversationHistoryPage[];
+};
+export type TurnContext = {
+    used: number;
+    window: number;
+};
+export type TurnOperation = {
+    op: 'begin';
+    at: string;
+} | {
+    op: 'start';
+    index: number;
+    part: unknown;
+} | {
+    op: 'append';
+    index: number;
+    text: string;
+} | {
+    op: 'status';
+    index: number;
+    status: string;
+    result: unknown;
+} | {
+    op: 'count';
+    index: number;
+    count: number;
+} | {
+    op: 'plan';
+    index: number;
+    entries: readonly unknown[];
+} | ({
+    op: 'context';
+} & TurnContext);
+export type ProcessCommand = {
+    [field: string]: unknown;
+    name: string;
+    description: string;
+    input?: {
+        [field: string]: unknown;
+        hint: string;
+    } | null;
+};
+type SelectValue = {
+    [field: string]: unknown;
+    value: string;
+    name: string;
+    description?: string | null;
+};
+type SelectGroup = {
+    [field: string]: unknown;
+    group: string;
+    name: string;
+    options: readonly SelectValue[];
+};
+type SessionOptionNaming = {
+    [field: string]: unknown;
+    id: string;
+    name: string;
+    description?: string | null;
+    category?: string | null;
+};
+export type SessionOption = (SessionOptionNaming & {
+    type: 'select';
+    currentValue: string;
+    options: readonly SelectValue[] | readonly SelectGroup[];
+}) | (SessionOptionNaming & {
+    type: 'boolean';
+    currentValue: boolean;
+});
+export type ConversationEvent = {
+    kind: 'turn';
+    conversation: string;
+    turn: string;
+    operation: TurnOperation;
+} | {
+    kind: 'questions';
+    conversation: string;
+    questions: readonly unknown[];
+} | {
+    kind: 'process';
+    conversation: string;
+    running: boolean;
+} | {
+    kind: 'commands';
+    conversation: string;
+    commands: readonly ProcessCommand[];
+} | {
+    kind: 'options';
+    conversation: string;
+    options: readonly SessionOption[];
+} | {
+    kind: 'starting';
+    conversation: string;
+    step: string | null;
+} | {
+    kind: 'link';
+    conversation: string;
+    connected: boolean;
+} | {
+    kind: 'deliveries';
+    conversation: string;
+    unknown: readonly string[];
+} | {
+    kind: 'accepted-message';
+    conversation: string;
+    message: AcceptedMessage;
+} | {
+    kind: 'gap';
+    conversation: string;
+} | {
+    kind: 'list';
+    entries: readonly ListedConversation[];
+} | {
+    kind: 'listed';
+    entry: ListedConversation;
+} | {
+    kind: 'unlisted';
+    conversation: string;
+};
+export type ConversationStream = {
+    replicate(conversations: readonly string[]): void;
+    observe(notify: (event: ConversationEvent) => void): () => void;
+};
+export type ActionDeclaration = {
+    name: string;
+    inputShape: unknown;
+    resultKind: unknown;
+    room?: string;
+};
+export type ProviderLimit = {
+    name: string;
+    value?: number | string;
+};
+export type HistoryRetention = {
+    kind: 'duration';
+    seconds: number;
+} | {
+    kind: 'no-declared-time-bound';
+};
+export type Retention = {
+    history: HistoryRetention;
+    outcome: number;
+    refreshHorizon: number;
+};
+export type Discovery = {
+    kind: 'discovery';
+    rooms: readonly DiscoveredRoom[];
+    capabilities: readonly Capability[];
+    providerLimits: readonly ProviderLimit[];
+    retention: Retention;
+    member?: Member;
+    covered?: readonly string[];
+};
+export type DiscoveryScope = {
+    readonly authorities: readonly string[];
+};
+export type TransportUncertainty = {
+    kind: 'transport-uncertainty';
+};
+export type RoomNotReadable = {
+    kind: 'room-not-readable';
+    locator: string;
+};
+export type RevokedAuthorization = {
+    kind: 'revoked-authorization';
+};
+export type ProviderRefusal = {
+    code: string;
+    fields: Readonly<Record<string, unknown>>;
+    retryable: boolean;
+};
+export type ScopedRefusal = ProviderRefusal & {
+    kind: 'scoped-refusal';
+    locator: string;
+    scope: Open<'content' | 'model' | 'operation' | 'undisclosed'>;
+};
+export type AdapterFailure = TransportUncertainty | RoomNotReadable | RevokedAuthorization | ScopedRefusal;
+export type ContractUnavailable = ProviderRefusal & {
+    kind: 'contract-unavailable';
+};
+export type DiscoverResult = Discovery | TransportUncertainty | RevokedAuthorization | ContractUnavailable;
+export type PageToken = string;
+export type ChangeAuthor = {
+    kind: Open<'user' | 'site' | 'inbox'>;
+    id: string;
+    name: string;
+};
+export type Member = {
+    kind: Open<'user'>;
+    id: string;
+    name: string;
+};
+export type HeadChange = {
+    author: ChangeAuthor | null;
+    time: string;
+};
+export type BinaryFile = {
+    byteLength: number;
+    mediaType: string;
+    sha256: string;
+};
+export type HeldFile = {
+    readonly path: string;
+    readonly revision: string;
+};
+export type HeldContent = {
+    files(after: string | null, limit: number): Promise<readonly HeldFile[]>;
+    contents(paths: readonly string[]): Promise<ReadonlyMap<string, {
+        readonly content: string;
+        readonly revision: string;
+    }>>;
+};
+export type BootstrapRequest = {
+    locator: string;
+    selection: string;
+    pageToken?: PageToken;
+    held?: HeldContent;
+    received?: Uint8Array;
+    arriving?: (bytes: number) => void;
+};
+export type BootstrapInventory = {
+    readonly parts: number;
+    readonly bytes: number;
+};
+export type RoomModels = {
+    collection?: ModelResult;
+};
+export type BootstrapPage = {
+    kind: 'bootstrap';
+    roomVersion: string;
+    models?: RoomModels;
+    documents: Readonly<Record<string, string>>;
+    revisions: Readonly<Record<string, string>>;
+    fileIds?: Readonly<Record<string, string>>;
+    changes: Readonly<Record<string, HeadChange>>;
+    binaryFiles: Readonly<Record<string, BinaryFile>>;
+    folders?: readonly string[];
+    pageToken?: PageToken;
+    inventory?: BootstrapInventory;
+    received?: Uint8Array;
+};
+export type BootstrapResult = BootstrapPage | {
+    kind: 'beyond-horizon';
+} | AdapterFailure;
+export type RefreshRequest = {
+    locator: string;
+    selection: string;
+    fromRoomVersion: string;
+    pageToken?: PageToken;
+};
+export type RefreshPage = {
+    kind: 'net-advancement';
+    roomVersion: string;
+    models?: RoomModels;
+    documents: Readonly<Record<string, string>>;
+    revisions: Readonly<Record<string, string>>;
+    fileIds?: Readonly<Record<string, string>>;
+    changes: Readonly<Record<string, HeadChange>>;
+    binaryFiles: Readonly<Record<string, BinaryFile>>;
+    removals: readonly string[];
+    folders?: readonly string[];
+    folderRemovals?: readonly string[];
+    pageToken?: PageToken;
+};
+export type RefreshResult = {
+    kind: 'still-current';
+} | RefreshPage | {
+    kind: 'beyond-horizon';
+} | RetryableRefusal | AdapterFailure;
+export type MutationRequest = {
+    locator: string;
+    changeBatch: ChangeBatch;
+    file(localId: string): Promise<Blob>;
+    upload?: unknown;
+};
+export type RetryableRefusal = ProviderRefusal & {
+    kind: 'retryable-refusal';
+    reset?: string;
+};
+export type ServiceMode = Open<'open' | 'write-halted'>;
+export type ServiceModeSignal = {
+    observe(notify: (mode: ServiceMode) => void): () => void;
+};
+export type AcceptedRoom = {
+    roomVersion: string;
+    documents: Readonly<Record<string, string>>;
+    revisions: Readonly<Record<string, string>>;
+    fileIds?: Readonly<Record<string, string>>;
+    changes: Readonly<Record<string, HeadChange>>;
+    removals: readonly string[];
+    binaryFiles?: Readonly<Record<string, BinaryFile>>;
+};
+export type MutationResult = (AcceptedRoom & {
+    kind: 'accepted';
+    author?: string;
+    time?: string;
+    destination?: AcceptedRoom;
+}) | (ProviderRefusal & {
+    kind: 'conflicted';
+    roomVersion?: string;
+    affected: Readonly<Record<string, string>>;
+}) | (ProviderRefusal & {
+    kind: 'rejected';
+    affected: Readonly<Record<string, string>>;
+}) | RetryableRefusal | {
+    kind: 'write-halted';
+} | {
+    kind: 'expired';
+    restored?: true;
+} | AdapterFailure;
+export type HistoryAuthor = {
+    kind: 'user';
+    id: string;
+} | {
+    kind: 'site' | 'inbox';
+    id: string;
+    name: string;
+};
+export type HistoryRevision = {
+    revision: string;
+    author: HistoryAuthor;
+    time: string;
+    binaryFile?: BinaryFile;
+};
+export type HistoryRequest = {
+    locator: string;
+    path: string;
+    revision?: string;
+    pageToken?: PageToken;
+};
+export type HistoryResult = {
+    kind: 'history';
+    revisions: readonly HistoryRevision[];
+    pageToken?: PageToken;
+    deleted?: true;
+} | {
+    kind: 'revision';
+    content: string;
+} | {
+    kind: 'no-history';
+} | AdapterFailure;
+export type BinaryRequest = {
+    kind: 'path';
+    locator: string;
+    path: string;
+    revision: string;
+};
+export type BinaryResult = {
+    kind: 'binary';
+    body: ReadableStream<Uint8Array>;
+    mediaType: string;
+    sha256?: string;
+} | (ProviderRefusal & {
+    kind: 'rejected';
+}) | AdapterFailure;
+export type BinaryLinkResult = {
+    kind: 'link';
+    url: string;
+    name: string;
+    mediaType?: string;
+} | (ProviderRefusal & {
+    kind: 'rejected';
+}) | AdapterFailure;
+export type AttachRequest = {
+    locator: string;
+    name: string;
+    mediaType: string;
+    byteLength: number;
+    sha256: string;
+    blob: Blob;
+};
+export type AttachResult = {
+    kind: 'attached';
+    path: string;
+    revision: string;
+} | (ProviderRefusal & {
+    kind: 'rejected';
+}) | AdapterFailure;
+export type ActionRequest = {
+    name: string;
+    input: unknown;
+};
+export type RoomVersionAt = {
+    locator: string;
+    roomVersion: string;
+};
+export type ActionResult = {
+    kind: 'action';
+    result: unknown;
+    at?: RoomVersionAt;
+} | (ProviderRefusal & {
+    kind: 'rejected';
+}) | AdapterFailure;
+export type HeldRoom = {
+    locator: string;
+    roomVersion: string;
+};
+export type HeldRevisions = (locator: string, paths: readonly string[]) => Promise<ReadonlyMap<string, string>>;
+export type RoomStreamEvent = {
+    kind: 'opened';
+} | {
+    kind: 'closed';
+    revoked: boolean;
+    lost: boolean;
+} | {
+    kind: 'opening';
+    expired: readonly string[];
+} | {
+    kind: 'authority-changed';
+    scope?: DiscoveryScope;
+} | {
+    kind: 'room-version';
+    locator: string;
+    roomVersion: string;
+};
+export type KeptReceipt = {
+    key: string;
+    head: unknown;
+};
+export type StreamReceipts = {
+    heads(): Promise<readonly KeptReceipt[]>;
+    parts(key: string, count: number): Promise<readonly unknown[]>;
+    keep(key: string, head: unknown, part?: {
+        index: number;
+        value: unknown;
+    }): Promise<void>;
+    drop(keys: readonly string[]): Promise<void>;
+};
+export type RoomStream = {
+    hold(rooms: readonly HeldRoom[]): void;
+    reopen(): void;
+    published(locator: string, roomVersion: string): void;
+    observe(notify: (event: RoomStreamEvent) => void, receipts: StreamReceipts, revisions: HeldRevisions): () => void;
+};
+export type Adapter = {
+    readonly localSaves?: true;
+    readonly exhaustiveDiscovery?: true;
+    readonly roomTypes?: string;
+    readonly nameableRoomTypes?: readonly string[];
+    authorize(): Promise<Authorization>;
+    discover(authorization: Authorization, scope?: DiscoveryScope): Promise<DiscoverResult>;
+    bootstrap(authorization: Authorization, request: BootstrapRequest): Promise<BootstrapResult>;
+    refresh(authorization: Authorization, request: RefreshRequest): Promise<RefreshResult>;
+    mutate(authorization: Authorization, request: MutationRequest, keep: (upload: unknown) => Promise<void>): Promise<MutationResult>;
+    history(authorization: Authorization, request: HistoryRequest): Promise<HistoryResult>;
+    binary(authorization: Authorization, request: BinaryRequest): Promise<BinaryResult>;
+    link(authorization: Authorization, request: BinaryRequest): Promise<BinaryLinkResult>;
+    attach(authorization: Authorization, request: AttachRequest): Promise<AttachResult>;
+    action(authorization: Authorization, request: ActionRequest): Promise<ActionResult>;
+    reached(locator: string, roomVersion: string, target: string): boolean;
+    follows(locator: string, roomVersion: string, next: string): boolean;
+    roomStream?: RoomStream;
+    conversations?: ConversationStream;
+    serviceMode?: ServiceModeSignal;
+};
+export {};

package/dist/mdruntime/binary.d.ts

@@ -0,0 +1,17 @@
+import type { HeldBinary } from './overlay.js';
+export type BinaryFileRecord = {
+    readonly state: 'accepted';
+    readonly revision: string;
+    readonly path: string;
+    readonly byteLength: number;
+    readonly mediaType: string;
+    readonly sha256: string;
+} | {
+    readonly state: 'pending';
+    readonly localId: string;
+    readonly path: string;
+    readonly byteLength: number;
+    readonly mediaType: string;
+    readonly sha256: string;
+};
+export declare function binaryRecord(path: string, held: HeldBinary, revision: string | undefined): BinaryFileRecord;

package/dist/mdruntime/chain.d.ts

@@ -0,0 +1,10 @@
+import type { MdRuntimeClient } from './client.js';
+import type { DocumentQuery, DocumentResult, GroupQuery, GroupResult, PendingResult } from './query.js';
+type Rows = DocumentResult | GroupResult;
+export type WindowAnswer = Rows | PendingResult;
+export type WindowChain = {
+    want(count: number): void;
+    close(): void;
+};
+export declare function chainedWindows(runtime: MdRuntimeClient, query: DocumentQuery | GroupQuery, count: number, publish: (answers: readonly (WindowAnswer | null)[], settled: boolean) => void): WindowChain;
+export {};

package/dist/mdruntime/change-set.d.ts

@@ -0,0 +1,27 @@
+export type DocumentChange = {
+    readonly locator: string;
+    readonly path: string | null;
+};
+export type ChangeSet = {
+    documents: readonly DocumentChange[];
+    drafts: readonly {
+        locator: string;
+        path: string;
+    }[];
+    rooms: readonly string[];
+    queues: readonly string[];
+    presentations: readonly string[];
+    conversations: readonly string[];
+};
+type Changed = {
+    documents?: readonly string[] | null;
+    drafts?: readonly string[];
+    room?: boolean;
+    queue?: boolean;
+    presentation?: string;
+};
+export declare function changeSet(locator: string, changed?: Changed): ChangeSet;
+export declare function conversationChangeSet(conversations: readonly string[]): ChangeSet;
+export declare function mergeChangeSets(sets: readonly ChangeSet[]): ChangeSet;
+export declare function touches(set: ChangeSet, locator: string, path: string): boolean;
+export {};