@agentshouse/app-bridge 0.1.0-ccf413b4e709d → 0.1.0-cd2d3edbf9805

package/dist/mdruntime/model.d.ts

@@ -0,0 +1,62 @@
+import type { Definition, ValueFacts, VerifiedModel } from '../mdmodel/index.js';
+import type { Open } from './open.js';
+export type ModelIdentity = {
+    identity: string;
+    version: string;
+};
+export type ModelSnapshot = ModelIdentity & {
+    schema: string | null;
+    revision: string | null;
+};
+export type ModelUnavailableReason = Open<'not-readable' | 'revoked' | 'not-acquired' | 'invalid'>;
+export type ModelResult = {
+    kind: 'model';
+    snapshot: ModelSnapshot;
+} | {
+    kind: 'model-unavailable';
+    reason: ModelUnavailableReason;
+};
+export type MdType = Definition;
+export type ModelState = {
+    status: 'unavailable';
+    reason: ModelUnavailableReason;
+    schema?: string | null;
+    revision?: string | null;
+} | {
+    status: 'current' | 'cached';
+    snapshot: ModelSnapshot;
+    verifiedWith: ModelIdentity;
+    types: VerifiedModel['types'];
+};
+export type StoredModel = Extract<ModelState, {
+    status: 'unavailable';
+}> | Omit<Extract<ModelState, {
+    status: 'current' | 'cached';
+}>, 'types'>;
+export type TypesResult = {
+    status: Open<'unavailable'>;
+    reason: ModelUnavailableReason;
+    types: null;
+    schema?: string | null;
+    revision?: string | null;
+} | {
+    status: Open<'current' | 'cached'>;
+    identity: string;
+    version: string;
+    verifiedWith: ModelIdentity;
+    types: readonly MdType[];
+    schema: string | null;
+    revision: string | null;
+};
+export type ValidationReceipt = {
+    identity: string;
+    version: string;
+    source: Open<'current' | 'cached'>;
+};
+export declare const NO_MODEL: ModelState;
+export declare function definitionOf(state: ModelState, type: string | undefined): Definition | undefined;
+export declare function modelTypes(state: ModelState): TypesResult;
+export declare function storedModel(state: ModelState): StoredModel;
+export declare function cached(state: ModelState): ModelState;
+export declare function sameModel(left: ModelIdentity, right: ModelIdentity): boolean;
+export declare function referenceField(facts: ValueFacts | undefined): boolean;

package/dist/mdruntime/observation.d.ts

@@ -0,0 +1,44 @@
+import type { QueryCoverage, QueryDocument, QueryGroup, QueryResult } from './query.js';
+export type Observation<T> = {
+    current(): T;
+    subscribe(listener: (value: T) => void): () => void;
+    close(): void;
+};
+export type RowKey = string | number;
+export type KeyedResult = {
+    result: QueryResult;
+    keys: readonly RowKey[];
+};
+export type QueryChange = {
+    changed: readonly (readonly [RowKey, QueryDocument | QueryGroup])[];
+    removed: readonly RowKey[];
+    order: readonly RowKey[] | null;
+    coverage?: QueryCoverage;
+    next?: string | null;
+    total?: number;
+};
+export type QueryMessage = KeyedResult | QueryChange;
+export type Observed = {
+    observation: Observation<unknown>;
+    receive(message: unknown): void;
+    end(): void;
+};
+export declare function rowsOf(result: QueryResult): readonly (QueryDocument | QueryGroup)[];
+export declare function whole(message: QueryMessage): message is KeyedResult;
+export declare function applied(keyed: KeyedResult, message: QueryMessage): KeyedResult;
+export declare function observed(first: unknown, stop: () => void, keyed: boolean): Observed;
+export declare function opened(watch: (deliver: (message: unknown) => void) => () => void, keyed: boolean): Promise<Observation<unknown>>;
+export declare function observing<Topic extends string>(watch: (topic: Topic, input: readonly unknown[], deliver: (message: unknown) => void) => () => void): (topic: Topic, ...input: unknown[]) => Promise<Observation<unknown>>;
+export type Digest = {
+    readonly pending: string;
+} | {
+    readonly keys: readonly RowKey[];
+    readonly rows: ReadonlyMap<RowKey, number>;
+    readonly coverage: string;
+    readonly next: string | undefined;
+    readonly total: number | undefined;
+};
+export declare function hashed(text: string): number;
+export declare function digestOf({ result, keys }: KeyedResult): Digest;
+export declare function digestApplied(digest: Digest, message: QueryMessage): Digest;
+export declare function changeOf(previous: Digest, next: KeyedResult): QueryMessage | null;

package/dist/mdruntime/open.d.ts

@@ -0,0 +1 @@
+export type Open<Value extends string> = Value | (string & {});

package/dist/mdruntime/opened.d.ts

@@ -0,0 +1,21 @@
+import type { BinaryResult } from './adapter.js';
+import { type RuntimeDatabase } from './tables.js';
+export type OpenedName = {
+    readonly locator: string;
+    readonly path: string;
+    readonly revision: string;
+};
+export type KeptBinary = {
+    readonly kind: 'binary';
+    readonly file: string;
+    readonly byteLength: number;
+    readonly mediaType: string;
+};
+export type KeptResult = KeptBinary | Exclude<BinaryResult, {
+    kind: 'binary';
+}>;
+export type OpenedFiles = {
+    find(name: OpenedName): Promise<KeptBinary | null>;
+    fetch(name: OpenedName, read: () => Promise<BinaryResult>): Promise<KeptResult>;
+};
+export declare function openedFiles(database: RuntimeDatabase, fenced: (locator: string) => boolean): OpenedFiles;

package/dist/mdruntime/outcome.d.ts

@@ -0,0 +1,84 @@
+import type { ActionResult, AdapterFailure, AttachResult, BinaryLinkResult, HistoryResult, HistoryRevision, ProviderRefusal, RoomVersionAt, ScopedRefusal } from './adapter.js';
+import type { ChangeBatch } from './change.js';
+import type { KeptBinary, KeptResult } from './opened.js';
+type Refused<Kind extends string> = ProviderRefusal & {
+    kind: Kind;
+};
+export type Failure = Refused<'transport-uncertainty'> | Refused<'revoked-authorization'> | (Refused<'room-not-readable'> & {
+    locator: string;
+}) | (Refused<'room-locked'> & {
+    locator: string;
+}) | ScopedRefusal;
+export type CallResult = {
+    kind: 'action';
+    result: unknown;
+    at?: RoomVersionAt;
+} | Refused<'rejected'> | Refused<'undeclared'> | Failure;
+export type HistoryAnswer = Exclude<HistoryResult, {
+    kind: Failure['kind'];
+}> | Failure;
+type BinaryRefusal = Refused<'rejected'> | Refused<'absent'> | Failure;
+export type BinaryAnswer = {
+    kind: 'binary';
+    stream: ReadableStream<Uint8Array>;
+    byteLength: number;
+    mediaType: string;
+} | BinaryRefusal;
+export type HeldBinaryAnswer = KeptBinary | BinaryRefusal;
+export type BinaryLinkAnswer = {
+    kind: 'link';
+    url: string;
+    name: string;
+    mediaType: string;
+} | Refused<'rejected'> | Refused<'absent'> | Failure;
+export type HeldShownAnswer = KeptBinary | BinaryLinkAnswer;
+export type ShownAnswer = BinaryAnswer | BinaryLinkAnswer;
+export type AttachAnswer = {
+    kind: 'attached';
+    path: string;
+} | Offline | Refused<'rejected'> | Failure;
+export type DownloadAnswer = {
+    kind: 'started';
+} | Refused<'rejected'> | Refused<'absent'> | Refused<'blocked'> | Failure;
+export type Resolution = {
+    readonly kind: 'document';
+    readonly room: string;
+    readonly path: string;
+} | {
+    readonly kind: 'deleted';
+    readonly room: string;
+    readonly path: string;
+    readonly revision: HistoryRevision;
+} | Refused<'unreadable'> | Refused<'absent'> | Failure;
+export declare const UNREADABLE: Refused<'unreadable'>;
+export declare const LOCKED_UNREADABLE: Refused<'unreadable'>;
+export declare const ABSENT_TARGET: Refused<'absent'>;
+export declare function absentBinary(path: string): Refused<'absent'>;
+export declare function binaryAnswer(result: KeptResult): HeldBinaryAnswer;
+export declare function binaryLinkAnswer(result: BinaryLinkResult, held?: string): BinaryLinkAnswer;
+export declare function attachAnswer(result: AttachResult): AttachAnswer;
+export declare const ROOM_LOCKED = "room-locked";
+export declare function lockedRoom(locator: string): Refused<'room-locked'> & {
+    locator: string;
+};
+export type Offline = {
+    readonly kind: 'offline';
+};
+export declare const OFFLINE: Offline;
+export declare const UNCERTAIN: Failure;
+export declare function undeclared(name: string): CallResult;
+export declare function failure(result: AdapterFailure): Failure;
+export declare function calledResult(result: ActionResult): CallResult;
+export declare function historyAnswer(result: HistoryResult): HistoryAnswer;
+export type Submission = {
+    readonly state: 'waiting' | 'submitted';
+} | {
+    readonly state: 'reset';
+    readonly reset: string;
+};
+export type QueueEntry = {
+    readonly batch: ChangeBatch;
+} & (Submission | {
+    readonly state: 'local';
+});
+export {};

package/dist/mdruntime/overlay.d.ts

@@ -0,0 +1,24 @@
+import type { BinaryFile, HeadChange } from './adapter.js';
+import type { ChangeBatch } from './change.js';
+export type Heads = {
+    revisions: Readonly<Record<string, string>>;
+    fileIds: Readonly<Record<string, string>>;
+    changes: Readonly<Record<string, HeadChange>>;
+};
+export type HeldBinary = ({
+    readonly state: 'accepted';
+} & BinaryFile) | {
+    readonly state: 'pending';
+    readonly localId: string;
+    readonly byteLength: number;
+    readonly mediaType: string;
+    readonly sha256: string;
+};
+export type Layer = Heads & {
+    documents: Readonly<Record<string, string>>;
+    binaries: Readonly<Record<string, HeldBinary>>;
+};
+export declare function acceptedBinaries(files: Readonly<Record<string, BinaryFile>>): Generator<readonly [string, HeldBinary]>;
+export declare function sameBinary(left: HeldBinary | undefined, right: HeldBinary | undefined): boolean;
+export declare function sameChange(left: HeadChange | undefined, right: HeadChange | undefined): boolean;
+export declare function overlaying(base: Layer, queue: readonly ChangeBatch[], unapplied?: () => void): Generator<number, Layer, void>;

package/dist/mdruntime/query.d.ts

@@ -0,0 +1,283 @@
+import { type Definition } from '../mdmodel/index.js';
+import type { HeadChange } from './adapter.js';
+import type { BinaryFileRecord } from './binary.js';
+import type { Open } from './open.js';
+export type Value = string | number | boolean | null;
+export type Predicate = Value | {
+    $eq: Value;
+} | {
+    $ne: Value;
+} | {
+    $in: readonly Value[];
+} | {
+    $nin: readonly Value[];
+} | {
+    $gt?: Value;
+    $gte?: Value;
+    $lt?: Value;
+    $lte?: Value;
+} | {
+    $all: readonly Value[];
+} | {
+    $size: number;
+} | {
+    $exists: boolean;
+};
+export type Where = {
+    $and?: readonly Where[];
+    $or?: readonly Where[];
+    [field: string]: Predicate | readonly Where[] | undefined;
+};
+export type Related = {
+    types?: readonly string[];
+    where?: Where;
+    pathPrefix?: string;
+};
+export type Filter = {
+    rooms?: readonly string[];
+    types?: readonly string[];
+    where?: Where;
+    pathPrefix?: string;
+    folder?: string;
+    paths?: readonly string[];
+    hop?: Related & {
+        field: string;
+    };
+    backlinks?: Related & {
+        field?: string;
+    };
+};
+export type Key = 'room' | 'path' | 'type' | 'folder' | {
+    field: string;
+};
+export type Select = 'all' | {
+    fields?: 'all' | readonly string[];
+    sections?: 'all' | readonly string[];
+    preamble?: true;
+    markdown?: true;
+    backlinks?: true;
+    change?: true;
+    fileId?: true;
+    revision?: true;
+};
+export type OrderOptions = {
+    nulls?: 'first' | 'last';
+    stringSort?: 'lexical' | 'locale';
+    locale?: string;
+    localeOptions?: Readonly<Record<string, unknown>>;
+};
+export type Direction = 'asc' | 'desc';
+export type DocumentQuery = Filter & {
+    select: Select;
+    orderBy?: readonly ({
+        by: Key;
+        direction?: Direction;
+    } & OrderOptions)[];
+    limit?: number;
+    after?: string;
+    total?: true;
+};
+export type GroupQuery = Filter & {
+    groupBy: readonly Exclude<Key, 'path'>[];
+    orderBy?: readonly {
+        by: 'count' | Exclude<Key, 'path'>;
+        direction?: Direction;
+    }[];
+    limit?: number;
+    after?: string;
+    total?: true;
+};
+export type LocalQuery = DocumentQuery | GroupQuery;
+export type Backlink = {
+    path: string;
+    type: string;
+    field: string;
+};
+export type QueryDocument = {
+    room: string;
+    path: string;
+    type?: string;
+    fields?: Readonly<Record<string, unknown>>;
+    sections?: Readonly<Record<string, string>>;
+    preamble?: string;
+    markdown?: string;
+    backlinks?: readonly Backlink[];
+    change?: HeadChange | null;
+    fileId?: string | null;
+    revision?: string | null;
+    binaryFile?: BinaryFileRecord;
+};
+export type QueryGroup = {
+    key: readonly unknown[];
+    count: number;
+};
+export type CoveredRoom = {
+    room: string;
+    generation: string;
+    current: boolean;
+};
+export type QueryCoverage = {
+    rooms: readonly CoveredRoom[];
+    indexes: readonly string[];
+    overlay: readonly string[];
+};
+export type Awaits = Open<'acquisition' | 'preparation' | 'unlock'>;
+export type PendingRoom = {
+    room: string;
+    awaits: Awaits;
+};
+export type PendingResult = {
+    pending: readonly PendingRoom[];
+};
+export type DocumentRows = {
+    documents: readonly QueryDocument[];
+    next?: string;
+    total?: number;
+};
+export type GroupRows = {
+    groups: readonly QueryGroup[];
+    next?: string;
+    total?: number;
+};
+export type QueryRows = DocumentRows | GroupRows;
+export type DocumentResult = DocumentRows & {
+    coverage: QueryCoverage;
+};
+export type GroupResult = GroupRows & {
+    coverage: QueryCoverage;
+};
+export type QueryResult = DocumentResult | GroupResult | PendingResult;
+export type QueryErrorCode = 'invalid-query' | 'unknown-type' | 'unknown-field' | 'wrong-kind';
+export type RoomFacts = {
+    locator: string;
+    available: boolean;
+    types: readonly Definition[];
+};
+export type HeldRooms = {
+    listed: boolean;
+    rooms: readonly RoomFacts[];
+};
+export type Test = {
+    op: 'eq';
+    value: Value;
+} | {
+    op: 'ne';
+    value: Value;
+} | {
+    op: 'in';
+    values: readonly Value[];
+} | {
+    op: 'nin';
+    values: readonly Value[];
+} | {
+    op: 'range';
+    bounds: readonly (readonly ['gt' | 'gte' | 'lt' | 'lte', Value])[];
+} | {
+    op: 'all';
+    values: readonly Value[];
+} | {
+    op: 'size';
+    size: number;
+} | {
+    op: 'exists';
+    exists: boolean;
+};
+export type Condition = {
+    every: readonly Condition[];
+} | {
+    some: readonly Condition[];
+} | {
+    field: string;
+    test: Test;
+};
+export type Scope = {
+    types: readonly string[] | null;
+    where: Condition | null;
+    pathPrefix: string | null;
+};
+export type KeyPlan = {
+    of: 'room';
+} | {
+    of: 'path';
+} | {
+    of: 'type';
+} | {
+    of: 'folder';
+} | {
+    of: 'field';
+    field: string;
+};
+export type DocumentShape = {
+    kind: 'documents';
+    fields: 'all' | readonly string[] | null;
+    sections: 'all' | readonly string[] | null;
+    preamble: boolean;
+    markdown: boolean;
+    backlinks: boolean;
+    change: boolean;
+    fileId: boolean;
+    revision: boolean;
+    orderBy: readonly {
+        key: KeyPlan;
+        options: OrderOptions & {
+            direction: Direction;
+        };
+    }[];
+};
+export type GroupShape = {
+    kind: 'groups';
+    groupBy: readonly KeyPlan[];
+    orderBy: readonly {
+        by: 'count' | number;
+        direction: Direction;
+    }[];
+};
+export type PlanArea = {
+    room: string;
+    path: string;
+    open: readonly string[];
+};
+export type PlanReach = {
+    rooms: readonly string[];
+    documents: readonly string[];
+    areas: readonly PlanArea[];
+};
+export type Continuation = {
+    text: string;
+    values: readonly unknown[] | null;
+};
+export type Plan = {
+    key: string;
+    rooms: readonly string[] | null;
+    reach: PlanReach | null;
+    locked: readonly string[];
+    root: Scope;
+    folder: string | null;
+    paths: readonly string[] | null;
+    hop: (Scope & {
+        field: string;
+    }) | null;
+    backlinks: (Scope & {
+        field: string | null;
+    }) | null;
+    shape: DocumentShape | GroupShape;
+    limit: number | null;
+    after: Continuation | null;
+    total: boolean;
+};
+export declare class QueryError extends Error {
+    readonly code: QueryErrorCode;
+    readonly retryable = false;
+    constructor(code: QueryErrorCode, at: string, problem: string);
+}
+type Entries = Readonly<Record<string, unknown>>;
+export declare function invalid(at: string, problem: string): never;
+export declare function plain(value: unknown): value is Entries;
+export declare function known(value: Entries, allowed: readonly string[], at: string): void;
+export declare function flag(input: unknown, at: string): boolean;
+export declare function planOf(input: unknown, facts: HeldRooms, reach?: PlanReach | null): Plan;
+export declare function limitOf(input: unknown): number | null;
+export declare function filterOf(input: unknown, facts: HeldRooms, reach?: PlanReach | null): Plan;
+export declare function queryKey(query: unknown): string;
+export declare function identityOf(plan: Plan): string;
+export {};

package/dist/mdruntime/reach.d.ts

@@ -0,0 +1,53 @@
+import type { AppRoom, MdRuntime, ReadinessPort, RuntimeTopic } from './connection.js';
+import type { Plan, PlanReach, QueryResult } from './query.js';
+import type { Readiness } from './readiness.js';
+import { type SearchResult } from './search.js';
+export type ReachedDocument = {
+    readonly room: string;
+    readonly path: string;
+};
+export type ReachedArea = {
+    readonly room: string;
+    readonly path: string;
+    readonly open: readonly string[];
+};
+export type PortReach = {
+    readonly rooms: readonly string[];
+    readonly documents: readonly ReachedDocument[];
+    readonly areas?: readonly ReachedArea[];
+    readonly conversations: boolean;
+};
+export type Deliver = (message: unknown) => void;
+export type Watch = (topic: RuntimeTopic, input: readonly unknown[], deliver: Deliver) => () => void;
+export type RuntimeView = {
+    md: MdRuntime;
+    watch: Watch;
+};
+export type NarrowedView = RuntimeView & {
+    narrow(reach: PortReach | null): void;
+    facts(port: ReadinessPort): void;
+};
+export type Reachable = RuntimeView & {
+    plan(input: unknown, reach: PortReach | null): Plan;
+    query(plan: Plan): Promise<QueryResult>;
+    watchPlan(plan: Plan, deliver: (message: unknown) => void): () => void;
+    search(input: unknown, reach: PortReach | null, locked: readonly string[]): Promise<SearchResult>;
+    watchReadiness(port: ReadinessPort, reach: PortReach | null, deliver: (readiness: Readiness) => void): () => void;
+    locked(room: string): boolean;
+    lockedRooms(): readonly string[];
+    watchLocks(notify: () => void): () => void;
+    located(room: string, path: string, destination: string): ReachedDocument | null;
+    room(locator: string): AppRoom | undefined;
+};
+export declare function holds(reach: PortReach | null, room: string): boolean;
+export declare function governs(reach: PortReach | null, room: {
+    readonly locator: string;
+    readonly typedSelection: {
+        roots: readonly string[];
+    } | null;
+}): {
+    readonly collection: boolean;
+    readonly selection: boolean;
+};
+export declare function planReach(reach: PortReach | null): PlanReach | null;
+export declare function narrowed(runtime: Reachable, given: PortReach | null, told: ReadinessPort): NarrowedView;

package/dist/mdruntime/readiness.d.ts

@@ -0,0 +1,51 @@
+import type { Open } from './open.js';
+export type CodeAvailability = Open<'stored' | 'absent'>;
+export type RoomPreparation = Open<'complete' | 'acquiring' | 'preparing' | 'unadmitted'>;
+export type RoomCoverage = {
+    readonly room: string;
+    readonly state: RoomPreparation;
+};
+export type ConversationCoverage = Open<'complete' | 'acquiring' | 'undeclared'>;
+export type SearchObligation = Open<'required' | 'unused'>;
+export type TargetCoverage = {
+    readonly complete: boolean;
+    readonly listed: boolean;
+    readonly rooms: readonly RoomCoverage[];
+    readonly conversations: ConversationCoverage;
+    readonly search: SearchObligation;
+};
+export type Persistence = Open<'granted' | 'denied' | 'unavailable'>;
+export type Durability = Open<'persistent' | 'best-effort'>;
+export type ConnectionAvailability = Open<'connected' | 'connecting' | 'unreachable'>;
+export type HouseOutcome = Open<'open' | 'write-halted' | 'refused'>;
+export type Space = Open<'full'>;
+export type InstallationStep = Open<'downloading' | 'writing' | 'replaying'>;
+export type InstallationAmount = {
+    readonly done: number;
+    readonly total: number;
+};
+export type Installation = {
+    readonly step: InstallationStep | null;
+    readonly rooms: InstallationAmount;
+    readonly bytes: InstallationAmount;
+};
+export type ReadinessStatus = Open<'preparing' | 'paused' | 'ready' | 'lost'>;
+export type Readiness = {
+    readonly status: ReadinessStatus;
+    readonly ready: boolean;
+    readonly usable: boolean;
+    readonly code: CodeAvailability;
+    readonly coverage: TargetCoverage;
+    readonly durability: Durability;
+    readonly persistence: Persistence;
+    readonly connection: ConnectionAvailability;
+    readonly house: HouseOutcome;
+    readonly space: Space | null;
+    readonly installation: Installation;
+    readonly lost: boolean;
+};
+export type ReadinessFacts = Omit<Readiness, 'status' | 'ready' | 'usable' | 'durability' | 'coverage'> & {
+    readonly coverage: Omit<TargetCoverage, 'complete'>;
+    readonly established: boolean;
+};
+export declare function readinessOf(facts: ReadinessFacts): Readiness;

package/dist/mdruntime/recovery.d.ts

@@ -0,0 +1,25 @@
+export type Attempted = 'done' | 'again' | {
+    readonly at: number;
+};
+export type Attempt = (signal: AbortSignal) => Promise<Attempted>;
+export type AttemptOptions = {
+    readonly at?: number;
+    readonly again?: boolean;
+};
+export type RecoveryOptions = {
+    readonly firstMs?: number;
+    readonly maxMs?: number;
+    readonly attempts?: number;
+    readonly inFlight?: number;
+};
+export type Recovery = {
+    attempt(intent: string, run: Attempt, options?: AttemptOptions): Promise<boolean>;
+    pending(intent: string): boolean;
+    resume(): void;
+    cancel(intent: string): void;
+    scope(inFlight?: number): Recovery;
+    retire(): Promise<void>;
+};
+export declare function retryDelay(tries: number, firstMs?: number, maxMs?: number): number;
+export declare function untilAnswered<T>(ask: () => Promise<T>, signal: AbortSignal, answered?: (answer: T) => boolean): Promise<T>;
+export declare function createRecovery(options?: RecoveryOptions): Recovery;