@agentshouse/mdruntime-families 0.1.0-cbbc2294ffb59 → 0.1.0-cbcba985a6e71

package/README.md

@@ -40,12 +40,15 @@ 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.
+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, or a page's total changes.
 
 ## License
 

package/dist/mdruntime/adapter.d.ts

@@ -0,0 +1,504 @@
+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 = {
+    read: readonly string[];
+    sync: readonly string[];
+    write: readonly string[];
+    delete: readonly string[];
+};
+export type ReplicaAdmission = {
+    selection: string;
+    admission: Open<'admitted' | 'unavailable'>;
+};
+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;
+};
+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;
+};
+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' | 'sync' | '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'>;
+    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 = {
+    fileRef: string;
+    byteLength: number;
+    mediaType: string;
+    sha256: string;
+};
+export type HeldContent = {
+    documents: Readonly<Record<string, string>>;
+    revisions: Readonly<Record<string, string>>;
+};
+export type BootstrapRequest = {
+    locator: string;
+    selection: string;
+    pageToken?: PageToken;
+    held?: HeldContent;
+};
+export type RoomModels = {
+    collection?: ModelResult;
+    selection?: 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>>;
+    pageToken?: PageToken;
+};
+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[];
+    pageToken?: PageToken;
+};
+export type RefreshResult = {
+    kind: 'still-current';
+} | RefreshPage | {
+    kind: 'beyond-horizon';
+} | RetryableRefusal | AdapterFailure;
+export type MutationRequest = {
+    locator: string;
+    changeBatch: ChangeBatch;
+    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 MutationResult = {
+    kind: 'accepted';
+    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>>;
+    author?: string;
+    time?: string;
+} | (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';
+    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;
+    fileRef?: string;
+} | {
+    kind: 'reference';
+    fileRef: string;
+    referrer: unknown;
+};
+export type ReferrerScope = {
+    kind: 'room';
+    locator: string;
+    path?: string;
+} | {
+    kind: 'conversations';
+};
+export type BinaryResult = {
+    kind: 'binary';
+    blob: Blob;
+} | (ProviderRefusal & {
+    kind: 'rejected';
+}) | AdapterFailure;
+export type BinaryLinkResult = {
+    kind: 'link';
+    url: string;
+    name: 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;
+    documents: Readonly<Record<string, string>>;
+    revisions: Readonly<Record<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): () => void;
+};
+export type Adapter = {
+    readonly localSaves?: true;
+    readonly exhaustiveDiscovery?: true;
+    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: Extract<BinaryRequest, {
+        kind: 'path';
+    }>): Promise<BinaryLinkResult>;
+    referrerScope(referrer: unknown): ReferrerScope | null;
+    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,22 @@
+import type { HeldBinary } from './overlay.js';
+export type BinaryFileRecord = {
+    readonly state: 'accepted';
+    readonly revision: string;
+    readonly path: string;
+    readonly fileRef: 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 type BinaryReference = {
+    readonly fileRef: string;
+    readonly referrer: unknown;
+};
+export declare function binaryRecord(path: string, held: HeldBinary, revision: string | undefined): BinaryFileRecord;

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

@@ -0,0 +1,37 @@
+import { type Replica } from './replica.js';
+import { type Row } from './rows.js';
+export type DocumentChange = {
+    locator: string;
+    path: string;
+    before: readonly Row[];
+    after: readonly Row[];
+};
+export type MessageChange = {
+    conversation: string;
+    identity: string;
+    text: string | null;
+};
+export type ChangeSet = {
+    documents: readonly DocumentChange[];
+    drafts: readonly {
+        locator: string;
+        path: string;
+    }[];
+    rooms: readonly string[];
+    queues: readonly string[];
+    presentations: readonly string[];
+    messages: readonly MessageChange[];
+    conversations: readonly string[];
+};
+type Changed = {
+    drafts?: readonly string[];
+    room?: boolean;
+    queue?: boolean;
+    presentation?: string;
+};
+export declare function changeSet(locator: string, before: Replica | null, after: Replica | null, changed?: Changed): ChangeSet;
+export declare function changing(locator: string, before: Replica | null, after: Replica | null, changed?: Changed): Generator<number, ChangeSet, void>;
+export declare function entering(locator: string, replica: Replica, paths: readonly string[]): ChangeSet;
+export declare function conversationChangeSet(messages: readonly MessageChange[], conversations: readonly string[]): ChangeSet;
+export declare function mergeChangeSets(sets: readonly ChangeSet[]): ChangeSet;
+export {};

package/dist/mdruntime/change.d.ts

@@ -0,0 +1,88 @@
+export type Change = {
+    readonly kind: 'field';
+    readonly path: string;
+    readonly name: string;
+    readonly value: unknown;
+} | {
+    readonly kind: 'section';
+    readonly path: string;
+    readonly name: string;
+    readonly value: string;
+} | {
+    readonly kind: 'preamble';
+    readonly path: string;
+    readonly value: string;
+} | {
+    readonly kind: 'create';
+    readonly path: string;
+    readonly fields: Readonly<Record<string, unknown>>;
+    readonly sections: Readonly<Record<string, string>>;
+} | {
+    readonly kind: 'create';
+    readonly path: string;
+    readonly content: string;
+} | {
+    readonly kind: 'replace';
+    readonly path: string;
+    readonly content: string;
+} | {
+    readonly kind: 'binary';
+    readonly path: string;
+    readonly localId: string;
+    readonly blob: Blob;
+    readonly byteLength: number;
+    readonly mediaType: string;
+    readonly sha256: string;
+} | {
+    readonly kind: 'move';
+    readonly path: string;
+    readonly to: string;
+} | {
+    readonly kind: 'remove';
+    readonly path: string;
+};
+export type Precondition = {
+    readonly kind: 'field';
+    readonly path: string;
+    readonly name: string;
+    readonly value: unknown;
+} | {
+    readonly kind: 'section';
+    readonly path: string;
+    readonly name: string;
+    readonly value: string;
+} | {
+    readonly kind: 'preamble';
+    readonly path: string;
+    readonly value: string;
+} | {
+    readonly kind: 'revision';
+    readonly path: string;
+    readonly revision: string;
+} | {
+    readonly kind: 'content';
+    readonly path: string;
+    readonly content: string;
+} | {
+    readonly kind: 'present';
+    readonly path: string;
+} | {
+    readonly kind: 'absent';
+    readonly path: string;
+};
+export type WrittenBy = {
+    readonly app: string;
+    readonly release: string;
+};
+export type ChangeBatch = {
+    validation?: import('./model.js').ValidationReceipt;
+    readonly id: string;
+    readonly baseRoomVersion: string;
+    readonly changes: readonly Change[];
+    readonly preconditions: readonly Precondition[];
+    readonly writtenBy?: WrittenBy;
+};
+export declare function immutable(batch: ChangeBatch): ChangeBatch;
+export declare function landing(changes: readonly Change[], index: number, path: string): string | null;
+export declare function departure(changes: readonly Change[], index: number): string;
+export declare function queuedFile(batch: ChangeBatch, path: string, localId: string): number;