@agentshouse/mdruntime 0.1.0-cf28918c2bf91 → 0.1.0-cf53a3b60b194

package/dist/query.d.ts

@@ -1,5 +1,7 @@
-import type { Definition } from '@agentshouse/mdmodel';
+import { type Definition } from '@agentshouse/mdmodel';
 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;
@@ -36,6 +38,8 @@ export type Filter = {
     types?: readonly string[];
     where?: Where;
     pathPrefix?: string;
+    folder?: string;
+    paths?: readonly string[];
     hop?: Related & {
         field: string;
     };
@@ -43,7 +47,7 @@ export type Filter = {
         field?: string;
     };
 };
-export type Key = 'room' | 'path' | 'type' | {
+export type Key = 'room' | 'path' | 'type' | 'folder' | {
     field: string;
 };
 export type Select = 'all' | {
@@ -53,6 +57,8 @@ export type Select = 'all' | {
     markdown?: true;
     backlinks?: true;
     change?: true;
+    fileId?: true;
+    revision?: true;
 };
 export type OrderOptions = {
     nulls?: 'first' | 'last';
@@ -68,6 +74,8 @@ export type DocumentQuery = Filter & {
         direction?: Direction;
     } & OrderOptions)[];
     limit?: number;
+    after?: string;
+    total?: true;
 };
 export type GroupQuery = Filter & {
     groupBy: readonly Exclude<Key, 'path'>[];
@@ -76,6 +84,8 @@ export type GroupQuery = Filter & {
         direction?: Direction;
     }[];
     limit?: number;
+    after?: string;
+    total?: true;
 };
 export type LocalQuery = DocumentQuery | GroupQuery;
 export type Backlink = {
@@ -93,18 +103,50 @@ export type QueryDocument = {
     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 DocumentResult = {
+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 GroupResult = {
+export type GroupRows = {
     groups: readonly QueryGroup[];
+    next?: string;
+    total?: number;
+};
+export type QueryRows = DocumentRows | GroupRows;
+export type DocumentResult = DocumentRows & {
+    coverage: QueryCoverage;
 };
-export type QueryResult = DocumentResult | GroupResult;
+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;
@@ -159,6 +201,8 @@ export type KeyPlan = {
     of: 'path';
 } | {
     of: 'type';
+} | {
+    of: 'folder';
 } | {
     of: 'field';
     field: string;
@@ -171,6 +215,8 @@ export type DocumentShape = {
     markdown: boolean;
     backlinks: boolean;
     change: boolean;
+    fileId: boolean;
+    revision: boolean;
     orderBy: readonly {
         key: KeyPlan;
         options: OrderOptions & {
@@ -186,9 +232,28 @@ export type GroupShape = {
         direction: Direction;
     }[];
 };
+export type PlanArea = {
+    room: string;
+    path: string;
+    types: 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;
@@ -197,17 +262,23 @@ export type Plan = {
     }) | 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 planOf(input: unknown, facts: HeldRooms): Plan;
+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): Plan;
+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 {};
 //# sourceMappingURL=query.d.ts.map

package/dist/query.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../src/query.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../src/query.ts"],"names":[],"mappings":"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"}

package/dist/query.js

@@ -1,16 +1,32 @@
+import { pointerFacts, } from '@agentshouse/mdmodel';
+import { referenceField } from './model.js';
 import { normalize } from './paths.js';
+import { decodedCursor } from './windows.js';
 export class QueryError extends Error {
+    code;
+    retryable = false;
     constructor(code, at, problem) {
         super(`${code} at ${at}: ${problem}`);
+        this.code = code;
     }
 }
 const RANGE = ['$gt', '$gte', '$lt', '$lte'];
 const SINGLE = ['$eq', '$ne', '$in', '$nin', '$all', '$size', '$exists'];
-const FILTER = ['rooms', 'types', 'where', 'pathPrefix', 'hop', 'backlinks'];
+const FILTER = ['rooms', 'types', 'where', 'pathPrefix', 'folder', 'paths', 'hop', 'backlinks'];
 const RELATED = ['types', 'where', 'pathPrefix', 'field'];
-const PARTS = ['fields', 'sections', 'preamble', 'markdown', 'backlinks', 'change'];
+const PARTS = [
+    'fields',
+    'sections',
+    'preamble',
+    'markdown',
+    'backlinks',
+    'change',
+    'fileId',
+    'revision',
+];
 const ORDER = ['by', 'direction', 'nulls', 'stringSort', 'locale', 'localeOptions'];
 const CALENDAR_DATE = /^(\d{4})-(\d{2})-(\d{2})$/;
+const STRAY_ESCAPE = /~(?![01])/u;
 export function invalid(at, problem) {
     throw new QueryError('invalid-query', at, problem);
 }
@@ -54,6 +70,13 @@ function names(input, at) {
         invalid(at, 'expects a list of names');
     return [...new Set(listed)].sort();
 }
+function pathsOf(input) {
+    const listed = list(input, 'paths');
+    if (listed.some((item) => typeof item !== 'string' || item === '' || normalize(item) !== item)) {
+        invalid('paths', 'expects a list of Paths');
+    }
+    return [...new Set(listed)].sort();
+}
 function directory(input, at) {
     if (typeof input !== 'string' || normalize(input) !== input) {
         invalid(at, 'expects a normalized directory');
@@ -68,23 +91,29 @@ function calendarDate(value) {
     const date = new Date(Date.UTC(year, month - 1, day));
     return (date.getUTCFullYear() === year && date.getUTCMonth() === month - 1 && date.getUTCDate() === day);
 }
-function fits(spec, value) {
-    const item = spec.kind === 'list' ? spec.of : spec;
-    if (item.kind === 'number')
+function itemOf(facts) {
+    return facts.type === 'array' ? facts.items : facts;
+}
+function fits(facts, value) {
+    const item = itemOf(facts);
+    if (item?.type === undefined)
+        return true;
+    if (item.values !== undefined)
+        return item.values.includes(value);
+    if (item.type === 'number')
         return typeof value === 'number';
-    if (typeof value !== 'string')
+    if (item.type === 'integer')
+        return Number.isSafeInteger(value);
+    if (item.type === 'boolean')
+        return typeof value === 'boolean';
+    if (item.type !== 'string' || typeof value !== 'string')
         return false;
-    if (item.kind === 'enum')
-        return item.values.includes(value);
-    if (item.kind === 'date')
-        return calendarDate(value);
-    if (item.kind === 'reference')
+    if (item.reference !== undefined)
         return value !== '' && normalize(value) === value;
+    if (item.format === 'date')
+        return calendarDate(value);
     return true;
 }
-function reference(spec) {
-    return spec.kind === 'reference' || (spec.kind === 'list' && spec.of.kind === 'reference');
-}
 function typing(facts, rooms, types, at) {
     const read = rooms === null ? facts.rooms : facts.rooms.filter((room) => rooms.includes(room.locator));
     const acquiring = !facts.listed &&
@@ -102,22 +131,46 @@ function typing(facts, rooms, types, at) {
         types: types === null ? declared : declared.filter((type) => types.includes(type.name)),
     };
 }
-function specs(typed, field, at) {
-    const declared = typed.types.flatMap((type) => Object.hasOwn(type.fields, field) ? [type.fields[field]] : []);
+function pointer(input, at) {
+    if (typeof input !== 'string' || !input.startsWith('/') || STRAY_ESCAPE.test(input)) {
+        invalid(at, 'expects a JSON Pointer');
+    }
+    return input;
+}
+function specs(typed, input, at) {
+    const field = pointer(input, at);
+    const declared = typed.types.flatMap((type) => {
+        const spec = pointerFacts(type, field);
+        return spec === undefined ? [] : [spec];
+    });
     if (declared.length === 0 && !typed.untyped) {
         throw new QueryError('unknown-field', at, `no MD Type it reads declares ${field}`);
     }
-    return declared;
+    if (!declared.some((spec) => spec.conditional))
+        return declared;
+    return declared.map((spec) => ({
+        facts: { prose: false },
+        through: several(spec),
+        conditional: true,
+    }));
+}
+function several(spec) {
+    return spec.through || spec.facts.type === 'array';
+}
+function single(spec) {
+    return spec.facts.type !== undefined && spec.facts.type !== 'array';
+}
+function every(declared, holds) {
+    return declared.length > 0 && declared.every(holds);
 }
 function kind(declared, checked, at) {
-    if (checked === null || declared.length === 0 || declared.some((spec) => fits(spec, checked))) {
+    if (checked === null ||
+        declared.length === 0 ||
+        declared.some((spec) => fits(spec.facts, checked))) {
         return;
     }
     throw new QueryError('wrong-kind', at, `${JSON.stringify(checked)} is not of its field's kind`);
 }
-function listed(declared, list) {
-    return declared.length > 0 && declared.every((spec) => (spec.kind === 'list') === list);
-}
 function test(declared, input, at) {
     if (!plain(input)) {
         const equal = value(input, at);
@@ -131,8 +184,11 @@ function test(declared, input, at) {
         const stray = operators.find((operator) => !RANGE.includes(operator));
         if (stray !== undefined)
             invalid(place(at, stray), 'cannot join a range');
-        if (listed(declared, true))
+        if (every(declared, (spec) => spec.facts.type === 'array'))
             invalid(at, 'a range on a list');
+        if (every(declared, (spec) => spec.facts.type === 'boolean' || spec.facts.type === 'object')) {
+            throw new QueryError('wrong-kind', at, 'its field does not compare in order');
+        }
         return {
             op: 'range',
             bounds: RANGE.filter((operator) => operators.includes(operator)).map((operator) => {
@@ -165,7 +221,7 @@ function test(declared, input, at) {
             return { op: 'nin', values: compared };
         if (compared.includes(null))
             invalid(where, 'a list holds no null');
-        if (listed(declared, false))
+        if (every(declared, single))
             invalid(where, 'the field is not a list');
         return { op: 'all', values: compared };
     }
@@ -173,7 +229,7 @@ function test(declared, input, at) {
         if (!Number.isSafeInteger(operand) || operand < 0) {
             invalid(where, 'expects a nonnegative integer');
         }
-        if (listed(declared, false))
+        if (every(declared, single))
             invalid(where, 'the field is not a list');
         return { op: 'size', size: operand };
     }
@@ -186,7 +242,7 @@ function condition(typed, input, at) {
         invalid(at, 'expects an object of field predicates');
     const conditions = [];
     for (const name of Object.keys(input).sort()) {
-        const where = place(at, name);
+        const where = name.startsWith('/') ? `${at}${name}` : place(at, name);
         const entry = input[name];
         if (name === '$and' || name === '$or') {
             const nested = list(entry, where).map((item, index) => condition(typed, item, `${where}[${index}]`));
@@ -215,19 +271,19 @@ function scope(facts, rooms, input, at) {
         pathPrefix: input.pathPrefix === undefined ? null : directory(input.pathPrefix, place(at, 'pathPrefix')),
     };
 }
-function referenceField(typed, field, at) {
-    if (typeof field !== 'string')
-        invalid(at, 'expects a field name');
+function referenceName(typed, field, at) {
     const declared = specs(typed, field, at);
-    if (declared.length > 0 && !declared.some(reference))
+    if (declared.length > 0 &&
+        !declared.some((spec) => spec.conditional || referenceField(spec.facts))) {
         invalid(at, 'not a reference field');
+    }
     return field;
 }
 function hopOf(facts, rooms, root, input) {
     if (!plain(input))
         invalid('hop', 'expects an object');
     known(input, RELATED, 'hop');
-    const field = referenceField(root, input.field, 'hop.field');
+    const field = referenceName(root, input.field, 'hop.field');
     const { types, where, pathPrefix } = scope(facts, rooms, input, 'hop');
     return { types, where, pathPrefix, field };
 }
@@ -236,17 +292,20 @@ function backlinksOf(facts, rooms, input) {
         invalid('backlinks', 'expects an object');
     known(input, RELATED, 'backlinks');
     const { typed, types, where, pathPrefix } = scope(facts, rooms, input, 'backlinks');
-    const field = input.field === undefined ? null : referenceField(typed, input.field, 'backlinks.field');
+    const field = input.field === undefined ? null : referenceName(typed, input.field, 'backlinks.field');
     return { types, where, pathPrefix, field };
 }
 function keyPlan(typed, input, at, path) {
-    if (input === 'room' || input === 'type' || (path && input === 'path'))
+    if (input === 'room' || input === 'type' || input === 'folder' || (path && input === 'path')) {
         return { of: input };
-    if (plain(input) && typeof input.field === 'string' && Object.keys(input).length === 1) {
-        specs(typed, input.field, place(at, 'field'));
+    }
+    if (plain(input) && Object.hasOwn(input, 'field') && Object.keys(input).length === 1) {
+        if (specs(typed, input.field, place(at, 'field')).some(several)) {
+            invalid(place(at, 'field'), 'a path that can hold several values');
+        }
         return { of: 'field', field: input.field };
     }
-    return invalid(at, path ? 'expects room, path, type or a field' : 'expects room, type or a field');
+    return invalid(at, path ? 'expects room, path, type, folder or a field' : 'expects room, type, folder or a field');
 }
 function direction(input, at) {
     if (input === undefined)
@@ -301,14 +360,14 @@ function parts(typed, input, at, fields) {
         return 'all';
     const named = list(input, at);
     named.forEach((name, index) => {
-        if (typeof name !== 'string')
-            invalid(`${at}[${index}]`, 'expects a name');
         if (fields)
             specs(typed, name, `${at}[${index}]`);
+        else if (typeof name !== 'string')
+            invalid(`${at}[${index}]`, 'expects a name');
     });
     return named;
 }
-function flag(input, at) {
+export function flag(input, at) {
     if (input === undefined)
         return false;
     if (input !== true)
@@ -336,6 +395,8 @@ function documentShape(typed, input) {
             markdown: true,
             backlinks: true,
             change: true,
+            fileId: true,
+            revision: true,
             orderBy,
         };
     }
@@ -350,6 +411,8 @@ function documentShape(typed, input) {
         markdown: flag(select.markdown, 'select.markdown'),
         backlinks: flag(select.backlinks, 'select.backlinks'),
         change: flag(select.change, 'select.change'),
+        fileId: flag(select.fileId, 'select.fileId'),
+        revision: flag(select.revision, 'select.revision'),
         orderBy,
     };
 }
@@ -372,7 +435,7 @@ function groupShape(typed, input) {
     });
     return { kind: 'groups', groupBy, orderBy };
 }
-export function planOf(input, facts) {
+export function planOf(input, facts, reach = null) {
     if (!plain(input))
         invalid('query', 'expects a query object');
     const grouped = input.groupBy !== undefined;
@@ -380,19 +443,36 @@ export function planOf(input, facts) {
         invalid('select', 'a grouped query selects nothing');
     if (!grouped && input.select === undefined)
         invalid('select', 'a Document query must select');
-    known(input, [...FILTER, 'orderBy', 'limit', grouped ? 'groupBy' : 'select'], '');
+    known(input, [...FILTER, 'orderBy', 'limit', 'after', 'total', grouped ? 'groupBy' : 'select'], '');
     const limit = limitOf(input.limit);
     const rooms = input.rooms === undefined ? null : names(input.rooms, 'rooms');
     const { typed, ...root } = scope(facts, rooms, input, '');
+    const shape = grouped ? groupShape(typed, input) : documentShape(typed, input);
     return {
+        key: queryKey(input),
         rooms,
+        reach,
+        locked: [],
         root,
+        folder: input.folder === undefined ? null : directory(input.folder, 'folder'),
+        paths: input.paths === undefined ? null : pathsOf(input.paths),
         hop: input.hop === undefined ? null : hopOf(facts, rooms, typed, input.hop),
         backlinks: input.backlinks === undefined ? null : backlinksOf(facts, rooms, input.backlinks),
-        shape: grouped ? groupShape(typed, input) : documentShape(typed, input),
+        shape,
         limit,
+        after: continuationOf(input.after, shape.orderBy.length + 1),
+        total: flag(input.total, 'total'),
     };
 }
+function continuationOf(input, arity) {
+    if (input === undefined)
+        return null;
+    const values = typeof input === 'string' ? decodedCursor(input) : null;
+    if (values === null || (values.length !== 0 && values.length !== arity)) {
+        invalid('after', 'expects the next an earlier result of this query returned');
+    }
+    return { text: input, values: values.length === 0 ? null : values };
+}
 export function limitOf(input) {
     if (input === undefined)
         return null;
@@ -401,11 +481,14 @@ export function limitOf(input) {
     }
     return input;
 }
-export function filterOf(input, facts) {
+export function filterOf(input, facts, reach = null) {
     if (!plain(input))
         invalid('documents', 'expects a filter object');
     known(input, FILTER, '');
-    return planOf({ ...input, select: {} }, facts);
+    return planOf({ ...input, select: {} }, facts, reach);
+}
+export function queryKey(query) {
+    return canonical(query);
 }
 function canonical(value) {
     if (Array.isArray(value))

package/dist/reach.d.ts

@@ -0,0 +1,54 @@
+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 types: 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;
+//# sourceMappingURL=reach.d.ts.map

package/dist/reach.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reach.d.ts","sourceRoot":"","sources":["../src/reach.ts"],"names":[],"mappings":"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"}