@agentshouse/app-bridge 0.1.0-c58a055eeaa71 → 0.1.0-c70153aac6ee3

package/dist/mdruntime/query.d.ts

@@ -0,0 +1,246 @@
+import { type Definition } from '../mdmodel/index.js';
+import type { HeadChange } from './adapter.js';
+import type { BinaryFileRecord } from './binary.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;
+    hop?: Related & {
+        field: string;
+    };
+    backlinks?: Related & {
+        field?: string;
+    };
+};
+export type Key = 'room' | 'path' | 'type' | {
+    field: string;
+};
+export type Select = 'all' | {
+    fields?: 'all' | readonly string[];
+    sections?: 'all' | readonly string[];
+    preamble?: true;
+    markdown?: true;
+    backlinks?: true;
+    change?: 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;
+};
+export type GroupQuery = Filter & {
+    groupBy: readonly Exclude<Key, 'path'>[];
+    orderBy?: readonly {
+        by: 'count' | Exclude<Key, 'path'>;
+        direction?: Direction;
+    }[];
+    limit?: number;
+};
+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;
+    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 = 'acquisition' | 'preparation' | 'index';
+export type PendingRoom = {
+    room: string;
+    awaits: Awaits;
+};
+export type PendingResult = {
+    pending: readonly PendingRoom[];
+};
+export type DocumentRows = {
+    documents: readonly QueryDocument[];
+};
+export type GroupRows = {
+    groups: readonly QueryGroup[];
+};
+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: '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;
+    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 PlanReach = {
+    rooms: readonly string[];
+    documents: readonly string[];
+};
+export type Plan = {
+    rooms: readonly string[] | null;
+    reach: PlanReach | null;
+    root: Scope;
+    hop: (Scope & {
+        field: string;
+    }) | null;
+    backlinks: (Scope & {
+        field: string | null;
+    }) | null;
+    shape: DocumentShape | GroupShape;
+    limit: number | null;
+};
+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 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 identityOf(plan: Plan): string;
+export {};

package/dist/mdruntime/reach.d.ts

@@ -0,0 +1,45 @@
+import type { ReferrerScope } from './adapter.js';
+import type { 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 PortReach = {
+    readonly rooms: readonly string[];
+    readonly documents: readonly ReachedDocument[];
+    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): Promise<SearchResult>;
+    searching(target: string): void;
+    watchReadiness(port: ReadinessPort, reach: PortReach | null, deliver: (readiness: Readiness) => void): () => void;
+    referrerScope(referrer: unknown): ReferrerScope | null;
+};
+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,52 @@
+import type { Open } from './open.js';
+export type CodeAvailability = Open<'stored' | 'absent'>;
+export type RoomPreparation = Open<'complete' | 'acquiring' | 'preparing' | 'indexing' | 'refused' | 'unadmitted'>;
+export type RoomCoverage = {
+    readonly room: string;
+    readonly state: RoomPreparation;
+};
+export type ConversationCoverage = Open<'complete' | 'acquiring' | 'indexing' | '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 CapacityCause = {
+    readonly cause: Open<'insufficient-space' | 'quota-exceeded'>;
+    readonly needed: number | null;
+    readonly available: number | null;
+};
+export type RefusedRoom = {
+    readonly room: string;
+    readonly file: string;
+    readonly rule: string;
+    readonly location: string | null;
+};
+export type ReadinessStatus = Open<'preparing' | 'paused' | 'refused' | '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 capacity: CapacityCause | null;
+    readonly refused: readonly RefusedRoom[];
+    readonly lost: boolean;
+};
+export type ReadinessFacts = Omit<Readiness, 'status' | 'ready' | 'usable' | 'durability' | 'coverage'> & {
+    readonly coverage: Omit<TargetCoverage, 'complete'>;
+    readonly established: boolean;
+};
+export declare const SETTLED_ROOMS: ReadonlySet<string>;
+export declare function readinessOf(facts: ReadinessFacts): Readiness;

package/dist/mdruntime/recovery.d.ts

@@ -0,0 +1,24 @@
+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 ceilingMs?: 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, ceilingMs?: number): number;
+export declare function createRecovery(options?: RecoveryOptions): Recovery;

package/dist/mdruntime/replica.d.ts

@@ -0,0 +1,45 @@
+import { type ChangeBatch } from './change.js';
+import { type Collection, type Composition } from './collection.js';
+import { type Layer } from './overlay.js';
+import type { MutationResult } from './adapter.js';
+import type { ReplicaRecord } from './store.js';
+import type { Refused } from './transfer.js';
+export type ConfirmedLayer = {
+    record: ReplicaRecord;
+    collection: Collection;
+};
+export type VisibleLayer = Layer & {
+    collection: Collection;
+};
+export type Staged = {
+    kind: 'staged';
+    confirmed: ConfirmedLayer;
+} | Refused;
+export type Replica = {
+    confirmed: ConfirmedLayer;
+    queue: readonly ChangeBatch[];
+    visible: VisibleLayer;
+    replay: readonly ReplayStep[];
+};
+type ReplayStep = {
+    id: string;
+    before: Layer;
+    after: Layer;
+    effective: ChangeBatch;
+    collection?: Collection;
+};
+export declare function compositionOf(record: ReplicaRecord): Composition;
+export declare function confirmedOf(record: ReplicaRecord, previous?: ConfirmedLayer): ConfirmedLayer;
+export declare function sameMembership(record: ReplicaRecord, other: ReplicaRecord): boolean;
+export declare function readStaged(staged: ReplicaRecord, previous?: ConfirmedLayer): Staged;
+export declare function readReclassified(record: ReplicaRecord, previous: ConfirmedLayer): Staged | {
+    kind: 'deferred';
+};
+type Accepted = Extract<MutationResult, {
+    kind: 'accepted';
+}>;
+export declare function applyReturned(confirmed: ConfirmedLayer, submitted: ChangeBatch, accepted: Accepted, roomVersion: string, writtenAt: string): Staged;
+export declare function replicaOf(confirmed: ConfirmedLayer, queue: readonly ChangeBatch[], previous?: Replica): Replica;
+export declare function landed(batch: ChangeBatch, confirmed: ConfirmedLayer, current?: Readonly<Record<string, string>>): boolean;
+export declare function withdrawals(confirmed: ConfirmedLayer, queue: readonly ChangeBatch[], withdrawable: (batch: ChangeBatch) => boolean, local: boolean): readonly ChangeBatch[];
+export {};

package/dist/mdruntime/room-draft.d.ts

@@ -0,0 +1,143 @@
+import type { ProviderRefusal } from './adapter.js';
+import type { Open } from './open.js';
+import type { Change, Precondition } from './change.js';
+import type { VisibleLayer } from './replica.js';
+export type FieldValue = {
+    readonly value: unknown;
+} | null;
+export type RoomDraftCreation = {
+    readonly type: string;
+    readonly fields: Readonly<Record<string, unknown>>;
+    readonly sections: Readonly<Record<string, string>>;
+} | {
+    readonly markdown: string;
+};
+export type RoomDraftParts = {
+    readonly fields?: Readonly<Record<string, {
+        readonly value: unknown;
+        readonly base?: FieldValue;
+    }>>;
+    readonly sections?: Readonly<Record<string, {
+        readonly value: string;
+        readonly base?: string;
+    }>>;
+    readonly preamble?: {
+        readonly value: string;
+        readonly base?: string;
+    };
+    readonly markdown?: {
+        readonly value: string;
+        readonly base?: string;
+    };
+    readonly creation?: RoomDraftCreation;
+    readonly move?: {
+        readonly to: string;
+        readonly base?: string | null;
+    };
+    readonly removal?: {
+        readonly base?: string | null;
+    };
+    readonly file?: {
+        readonly blob: Blob;
+    };
+};
+export type HeldFile = {
+    readonly blob: Blob;
+    readonly localId: string;
+    readonly byteLength: number;
+    readonly mediaType: string;
+    readonly sha256: string;
+    readonly base: string | null;
+};
+type HeldParts = {
+    readonly fields?: Readonly<Record<string, {
+        readonly value: unknown;
+        readonly base: FieldValue;
+    }>>;
+    readonly sections?: Readonly<Record<string, {
+        readonly value: string;
+        readonly base: string;
+    }>>;
+    readonly preamble?: {
+        readonly value: string;
+        readonly base: string;
+    };
+    readonly markdown?: {
+        readonly value: string;
+        readonly base: string;
+    };
+    readonly creation?: RoomDraftCreation;
+    readonly move?: {
+        readonly to: string;
+        readonly base: string | null;
+    };
+    readonly removal?: {
+        readonly base: string | null;
+    };
+    readonly file?: HeldFile;
+};
+type ChangedUnderneath = {
+    readonly fields?: Readonly<Record<string, FieldValue>>;
+    readonly sections?: Readonly<Record<string, string | null>>;
+    readonly preamble?: string | null;
+    readonly markdown?: string | null;
+    readonly creation?: string;
+    readonly move?: string | null;
+    readonly removal?: string | null;
+    readonly file?: string | null;
+};
+export type ReturnReason = ProviderRefusal & {
+    readonly kind: 'conflicted' | 'rejected' | 'expired' | 'withdrawn';
+};
+export declare function returnedBy(kind: 'expired' | 'withdrawn'): ReturnReason;
+export type RoomDraft = {
+    readonly room: string;
+    readonly path: string;
+    readonly revision: string;
+    readonly parts: HeldParts;
+    readonly changedUnderneath: ChangedUnderneath;
+    readonly returned: ReturnReason | null;
+};
+export type RoomDraftWrite = {
+    readonly outcome: 'written';
+    readonly roomDraft: RoomDraft | null;
+} | {
+    readonly outcome: 'stale';
+    readonly code: string;
+    readonly retryable: boolean;
+    readonly current: RoomDraft | null;
+};
+export declare function staleWrite(current: RoomDraft | null): RoomDraftWrite;
+export type ChangedPart = {
+    readonly path: string;
+    readonly part: Open<'field' | 'section' | 'preamble' | 'markdown' | 'creation' | 'move' | 'removal' | 'file'>;
+    readonly name?: string;
+};
+export type RoomDraftRecord = {
+    readonly locator: string;
+    readonly path: string;
+    readonly revision: string;
+    readonly parts: HeldParts;
+    readonly returned: ReturnReason | null;
+};
+export type SavedDraft = {
+    readonly path: string;
+    readonly parts: HeldParts;
+};
+export declare function readParts(value: unknown): RoomDraftParts;
+export declare function held(current: HeldParts | undefined, parts: RoomDraftParts, file?: HeldFile): HeldParts;
+export declare function underneath(parts: HeldParts, path: string, visible: VisibleLayer | undefined): ChangedUnderneath;
+export declare function heldFile(blob: Blob, base: string | null): Promise<HeldFile>;
+export declare function binaryBase(visible: VisibleLayer | undefined, path: string): string | null;
+export declare function changedParts(path: string, report: ChangedUnderneath): readonly ChangedPart[];
+export declare function returnedInto(existing: HeldParts | undefined, returned: HeldParts): HeldParts;
+export declare function moveTarget(move: {
+    readonly to: string;
+}): string;
+export declare function changesOf(path: string, parts: HeldParts): {
+    changes: readonly Change[];
+    bases: readonly Precondition[];
+};
+export declare function joinedDraft(carried: SavedDraft, saved: readonly SavedDraft[]): SavedDraft;
+export declare function withdrawnDrafts(drafts: readonly SavedDraft[], changes: readonly Change[]): readonly SavedDraft[];
+export {};

package/dist/mdruntime/rows.d.ts

@@ -0,0 +1,36 @@
+import { type Frontmatter } from '../mdmodel/index.js';
+import type { HeadChange } from './adapter.js';
+import type { BinaryFileRecord } from './binary.js';
+import { type Composition } from './collection.js';
+type Fields = Readonly<Record<string, unknown>>;
+export type DocumentRow = {
+    key: string;
+    kind: 'document';
+    room: string;
+    path: string;
+    type: string | null;
+    fields: Fields;
+    values: Fields;
+    reached: Readonly<Record<string, readonly unknown[]>>;
+    directories: readonly string[];
+    text: string | null;
+    change: HeadChange | null;
+    binary: BinaryFileRecord | null;
+};
+export type ReferenceRow = {
+    key: string;
+    kind: 'reference';
+    room: string;
+    source: string;
+    target: string;
+    field: string;
+    forms: readonly string[];
+    path: string;
+    type: string;
+};
+export type Row = DocumentRow | ReferenceRow;
+export declare function documentKey(room: string, path: string): string;
+export declare function roomOfKey(key: string): string;
+export declare function markdownPath(path: string): boolean;
+export declare function rowsOf(room: string, path: string, document: Frontmatter | null, composition: Composition, change: HeadChange | null, binary: BinaryFileRecord | null): readonly Row[];
+export {};

package/dist/mdruntime/save.d.ts

@@ -0,0 +1,63 @@
+import type { ProviderLimit } from './adapter.js';
+import { type Change, type ChangeBatch, type Precondition, type WrittenBy } from './change.js';
+import { type Composition } from './collection.js';
+import type { VisibleLayer } from './replica.js';
+import type { ChangedPart } from './room-draft.js';
+export type SaveRefusal = {
+    code: string;
+    retryable: boolean;
+    file?: string;
+    location?: string;
+    referrers?: readonly string[];
+    parts?: readonly ChangedPart[];
+};
+export type SaveInput = {
+    local: boolean;
+    composition: Composition;
+    baseRoomVersion: string;
+    operations: import('./adapter.js').OperationScopes;
+    providerOwnedPaths: readonly string[];
+    providerLimits: readonly ProviderLimit[];
+    visible: VisibleLayer;
+    handle: string;
+    changes: readonly Change[];
+    bases: readonly Precondition[];
+    queued?: ReadonlySet<string>;
+    writtenBy?: WrittenBy;
+    clean?: {
+        text: Readonly<Record<string, string>>;
+        binaries: Readonly<Record<string, unknown>>;
+        composition: Composition;
+    };
+};
+export type BatchResult = {
+    kind: 'batch';
+    batch: ChangeBatch;
+} | {
+    kind: 'refused';
+    refusal: SaveRefusal;
+};
+export declare function providerRewritten(batch: ChangeBatch, visible: VisibleLayer): ChangeBatch;
+export type Requeued = {
+    kind: 'requeued';
+    queue: readonly ChangeBatch[];
+    changes: readonly Change[];
+    queued: ReadonlySet<string>;
+    withdrawn: ReadonlyMap<string, ChangeBatch | null>;
+    owners: ReadonlySet<string>;
+} | {
+    kind: 'refused';
+    refusal: SaveRefusal;
+};
+export type Joining = {
+    kind: 'joined';
+    batch: ChangeBatch;
+    queue: readonly ChangeBatch[];
+} | {
+    kind: 'refused';
+    refusal: SaveRefusal;
+};
+export declare function requeued(queue: readonly ChangeBatch[], changes: readonly Change[], visible: VisibleLayer, changeable: (batch: ChangeBatch) => boolean, state: (queue: readonly ChangeBatch[]) => VisibleLayer): Requeued;
+export declare function joined(queue: readonly ChangeBatch[], owner: ChangeBatch, extra: ChangeBatch): Joining;
+export declare function limitedIn(queue: readonly ChangeBatch[], batch: ChangeBatch, limits: readonly ProviderLimit[], state: (queue: readonly ChangeBatch[]) => VisibleLayer): SaveRefusal | null;
+export declare function buildBatch(input: SaveInput): BatchResult;