@agentshouse/mdruntime-adapter 0.1.0-cc63dd043d0e2 → 0.1.0-cc7da2d4669a3

package/AGENTS.md

@@ -1,215 +0,0 @@
-# Instructions for the App Creator's agent
-
-These instructions address an agent in an environment with Git. Obtain the
-App Repository, change it, build, and push. They are documentation, not
-enforcement.
-
-## The MD Runtime API
-
-App code reaches the MD Runtime through the remote client. The surfaces are
-Rooms, Query, Search, Observe, Types, Room Draft, Save, History, Call, Reached, Log,
-the reported persistence answer, reauthorization, conversation, the chat draft,
-and Presentation State. Sync Status, the Service Mode, the storage-loss
-statement and the deployment facts are observations only.
-
-The host attaches each port with its reach, and every member and observation
-answers within it: a Room outside it answers as one the replica does not hold, a
-Room reached for single Documents shows only those Documents, the Types of the
-models that govern them and no attachments, and without conversations the
-conversation members, the chat draft and the conversation observation hold none.
-A change of the reach reaches every open observation as its new value, a query
-keeping every unchanged Document the same object.
-
-Every `observe` resolves, once its first value has arrived, to a handle:
-`current()` is the latest complete value, `subscribe(listener)` hears each later
-value whole and returns its unsubscribe, and `close()` ends the observation.
-Closing the port ends every handle and rejects every pending call and
-observation; a client that reconnects observes again.
-
-Each conversation a Provider card names is held complete in the browser.
-Observe one with `observe('conversation', id, { limit })`: the view
-holds its latest `limit` messages, or all of them, oldest first, its chat
-draft, and what the Provider streams for it whether or not anything views it:
-the running `turn` with its message parts and its context in use and window, the
-open questions, the process state, and the CLI's commands and options. These live
-only in memory: the message accepted under the turn's id replaces the running turn,
-and none of them is stored or searchable.
-`chatDraft.write` and `chatDraft.discard` keep what the App Creator composes;
-sending it is a Provider Action that needs the Provider reachable and is never
-queued.
-
-Each Room in Rooms lists its `attachments`, the files the Provider holds for it
-that its Documents link by the Provider's reference, ordered by `reference`,
-each with `name`, `byteLength`, `mediaType` and the Provider's own entry as
-`entry`. They are as the Provider last declared them and hold no bytes;
-open one through the Provider Action that serves it.
-
-Rooms, Query, Search, Observe, Types, Room Draft, Save, and Reached never
-touch the network.
-History and Call go to the Provider through the Adapter. A Call result whose
-effect the Provider places in a Room carries `at`, that Room and Room Version;
-`reached(room, roomVersion)` answers whether the Room's confirmed state has
-reached it, and the MD Runtime keeps refreshing that Room until it has;
-`reached(room, roomVersion, path)` answers whether the held confirmed copy of
-that document was written at a later Room Version. Each History revision
-names its author, `{ kind: 'user', id }` or `{ kind: 'site', id, name }`. Every
-member of the
-client is asynchronous. Results are detached snapshots. Nothing in this
-surface returns the authorization, performs a request the App's code
-composes, or exposes the browser store.
-
-Read the deployment facts with `observe('deployment-facts')`. Interpret the
-opaque value using the host's contract.
-
-The in-memory Adapter at `@agentshouse/mdruntime/memory` is for tests and
-ships in no bundle.
-
-## Local Query rules
-
-`query(q)` answers once from local state; `observe('query', q)` holds the whole
-result and hears it again only when it changes, keeping every unchanged Document
-the same object, so a component can tell what changed by identity. A query is
-data:
-
-- **Filter.** `rooms` names Room locators and defaults to every Room. `types`
-  names MD Types, and `any` names untyped Markdown Documents. `pathPrefix` is a
-  directory: `notes` keeps `notes/a.md` and not `notes2/a.md`.
-- **Fields.** `where` names frontmatter fields, ANDs them, and nests `$and` and
-  `$or`. A bare value is equality; the operators are `$eq`, `$ne`, `$in`, `$nin`,
-  `$gt`, `$gte`, `$lt`, `$lte`, `$all`, `$size` and `$exists`. Equality on a list
-  asks whether it contains the value. Missing, null and empty differ:
-  `$exists: false` keeps a missing field, `null` an explicit null, `''` empty
-  text and `$size: 0` an empty list. A date compares in calendar order and never
-  with a date-time. A reference compares by the Room Path it resolves to.
-  Untyped frontmatter is plain values. There is no text containment or regular
-  expression.
-- **Relations.** `hop: { field, types, where, pathPrefix }` keeps Documents whose
-  reference `field` points to a matching Document of the same Room.
-  `backlinks: { field, types, where, pathPrefix }` keeps Documents that a
-  matching Document of the same Room references. Each keeps a Document once.
-- **Parts.** A Document query must `select`: `'all'`, or `fields`, `sections`,
-  `preamble`, `markdown`, `backlinks` and `change`, where `fields` and `sections`
-  are `'all'` or a list of names. Room and Path always return; a Markdown
-  Document also returns its MD Type. A non-Markdown Document or binary link
-  target returns only Room and Path. An unselected part is absent. Select only
-  what a screen shows: a list that selects the Markdown hears every edit of it.
-- **Change.** `change` is `{ author, time }` of the Document's head revision as
-  the Provider last delivered it: `author` is `{ kind: 'user' | 'site', id, name }`
-  or `null` for a write the Provider made itself, and `time` is the Provider's
-  ISO 8601 change time. It is `null` where the Provider delivered no time, as at
-  a Site. An unsent edit or move keeps it, an unsent creation has none, and a
-  saved write takes the Provider's own once it is Accepted and refreshed. A
-  Room's last change is its Document with the latest `time`.
-- **Order and groups.** `orderBy` sorts by `room`, `path`, `type` or `{ field }`
-  with TanStack DB's own options, and ties end with Room, then Path. `groupBy` by
-  `room`, `type` or `{ field }` answers `{ groups: [{ key, count }] }`, counted
-  over every match and ordered by `count` or a key. `limit` bounds the Documents
-  or the groups.
-- **Results and errors.** A result carries no Room Version: read freshness from
-  Rooms and Sync Status. An invalid query fails with `invalid-query`,
-  `unknown-type`, `unknown-field` or `wrong-kind`, naming where, and never
-  answers an empty result in its place.
-
-## Local Search rules
-
-`search({ text, documents, conversations, limit })` answers once, by words, from
-local state, with MiniSearch at its default configuration. There is no observed
-search.
-
-- **What is found.** A Document by its field values, its sections' headings and
-  text, its preamble and its Path; a message by its text. Frontmatter keys, Room
-  Drafts, chat drafts and a running turn's parts are never found. There are no phrases,
-  word forms, typo tolerance or prefix matching.
-- **Narrowing.** `documents` is a Local Query filter: `rooms`, `types`, `where`,
-  `pathPrefix`, `hop` and `backlinks`. `conversations` names conversations. Both
-  apply before `limit`, which bounds each list; without it every hit returns.
-- **Results.** `{ documents, messages }`, each ranked by `score`, which compares
-  hits of one list of one search. A Document hit names its `room`, `path` and
-  `type`, a message hit its `conversation` and `identity`, and `matches` maps each
-  matched word to the parts it matched in: `fields`, `sections`, `preamble` or
-  `path`, or `text`. A hit carries no position; mark the words in the text you
-  show. An invalid filter fails with its Local Query error.
-
-## Room Draft, Save, and outcome rules
-
-The MD Runtime owns one Room Draft per Room and Path, shared by every App and
-tab. It is durable: it survives reload and navigation. A Room that Discovery
-stops listing takes its Room Drafts and its queue with it.
-Write a Room Draft with `roomDraft.write(room, path, revision, parts)`, naming
-the revision you read, or `null` when there was none, and every part it should
-now change: fields, sections and the preamble, or the whole Markdown, a
-creation, a move, or a removal. A part new to the Room Draft names its base,
-the value you showed when it was opened; the MD Runtime keeps a part's first
-base. A binary link target has a Room Draft too, for a move or a removal, with
-`null` as its base. A write or a discard from an older revision is refused as `stale` with
-the current Room Draft; read it and write again.
-
-Save takes one Room and the Room Drafts of it to save, each with its revision,
-validates locally, and on success appends one Change Batch to that Room's
-queue and removes those Room Drafts. It is refused as `stale`, as
-`changed-underneath` naming each part whose base no longer matches the visible
-state, or by a local validation rule, and then creates nothing and leaves every
-Room Draft in place. A directory move or removal is a move or removal part on
-each Document and binary link target beneath it, saved together.
-
-Outcomes follow the Provider's answer. An Accepted Change Batch stays in the
-queue, drawn over the confirmed layer, until the confirmed layer reaches the
-Room Version it was accepted at, and then leaves it. Conflicted and Rejected, an expired operation, and a change that no
-longer applies over the Room each leave the queue and return as Room Drafts on
-the Documents they changed, marked with why: the Provider's structured refusal
-code and fields as returned, not known to have applied, or withdrawn locally.
-The rest of the queue keeps synchronizing, and Sync Status requires attention
-until each returned Room Draft is saved again or discarded. A Change Batch
-keeps no outcome once it leaves the queue; `observe('queue', room)` shows each
-Pending one, and a returned Room Draft says why it returned. Transport
-failure and Provider unavailability keep work Pending and do not infer a
-rejection. A refusal the Provider marks retryable stays Pending until the reset
-it names; the MD Runtime retries the same Change Batch identity and payload and
-never infers an outcome from transport uncertainty. The MD Runtime never
-combines, reorders, or rebases.
-
-`observe('service-mode')` answers the Provider's Service
-Mode, `open` or `write-halted`. While writes are halted, Save still succeeds,
-its Change Batch waits unsent, and the queue is submitted in order once the
-Provider reopens writes. An Action is never held: a write the Provider refuses
-for the halt returns that refusal to its caller. Show the Provider as read-only
-instead of retrying.
-
-## The neutrality rule
-
-No module outside an Adapter package imports, names, or special-cases a
-Provider. MD UI and every App reach data only through the client entry.
-
-## Content-safety rules
-
-The Provider authorization belongs to the Runtime host and is never readable
-by the App's code. The App's code reaches the network only at the external
-origins its manifest declares, empty by default, and the Provider enforces
-that set. Every request to the Provider itself goes through the MD Runtime.
-Rendered Markdown never executes scripts, renders raw HTML only for the
-details and summary elements, and loads images and other resources only from
-origins the Provider's policy allows.
-
-## Launch promises MD UI keeps
-
-MD UI uses semantic HTML, is fully operable from a keyboard with visible
-focus and labelled controls, and lays out from a 360 pixel wide viewport to
-a desktop. Its strings are English only, dates and numbers follow the
-browser locale, and content is never translated. Light and dark themes come
-from CSS custom properties with the browser's preference as the default and
-an App's override respected. What an App Creator's agent adds carries none
-of these promises by itself. Reading, querying and searching never wait for
-the network. Data lives only in the App Creator's browser and with the Provider.
-
-## App code imports only the client entry and never constructs a Runtime
-
-App code imports only `@agentshouse/mdruntime/client` and calls
-`connectMdRuntime` on the port the host hands it. It never constructs a
-Runtime. It does not import the package main, the host entry, or the Adapter
-package, and it does not call `serveMdRuntime`. Hosts
-and tests use those entries; the served App does not.
-
-## What an agent must never do
-
-An agent must never read the authorization, load code from a Room, call the
-Provider directly, or rebase a refused Change Batch.

package/dist/gather.d.ts

@@ -1,3 +0,0 @@
-export declare function gathered<A, R>(send: (asks: readonly A[]) => Promise<readonly R[]>): (ask: A) => Promise<R>;
-export declare function selections<T>(items: readonly T[], weight: (item: T) => number, limit: number): readonly (readonly T[])[];
-//# sourceMappingURL=gather.d.ts.map

package/dist/gather.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"gather.d.ts","sourceRoot":"","sources":["../src/gather.ts"],"names":[],"mappings":"AAMA,wBAAgB,QAAQ,CAAC,CAAC,EAAE,CAAC,EAC3B,IAAI,EAAE,CAAC,IAAI,EAAE,SAAS,CAAC,EAAE,KAAK,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC,GAClD,CAAC,GAAG,EAAE,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,CA0BxB;AAED,wBAAgB,UAAU,CAAC,CAAC,EAC1B,KAAK,EAAE,SAAS,CAAC,EAAE,EACnB,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,MAAM,EAC3B,KAAK,EAAE,MAAM,GACZ,SAAS,CAAC,SAAS,CAAC,EAAE,CAAC,EAAE,CAgB3B"}

package/dist/gather.js

@@ -1,40 +0,0 @@
-export function gathered(send) {
-    let held = [];
-    function flush() {
-        const taken = held;
-        held = [];
-        send(taken.map((entry) => entry.ask)).then((answers) => {
-            taken.forEach((entry, index) => {
-                entry.resolve(answers[index]);
-            });
-        }, (reason) => {
-            for (const entry of taken)
-                entry.reject(reason);
-        });
-    }
-    return (ask) => new Promise((resolve, reject) => {
-        if (held.length === 0) {
-            // Asks made in one task wait a single event-loop turn so they leave as one batch.
-            setTimeout(flush, 0);
-        }
-        held.push({ ask, resolve, reject });
-    });
-}
-export function selections(items, weight, limit) {
-    const parts = [];
-    let part = [];
-    let carried = 0;
-    for (const item of items) {
-        const weighed = weight(item);
-        if (part.length > 0 && carried + weighed > limit) {
-            parts.push(part);
-            part = [];
-            carried = 0;
-        }
-        part.push(item);
-        carried += weighed;
-    }
-    if (part.length > 0)
-        parts.push(part);
-    return parts;
-}

package/dist/links.d.ts

@@ -1,12 +0,0 @@
-import type { HouseScope, HouseView } from './read.js';
-import type { StreamedAdvancement } from './stream.js';
-export type RoomLinks = {
-    roomVersion: string;
-    handed: ReadonlySet<string>;
-    paths: ReadonlyMap<string, ReadonlySet<string>>;
-    revisions: ReadonlyMap<string, string>;
-};
-export declare function scopeLinks(scope: HouseScope): RoomLinks;
-export declare function enumeratedLinks(view: HouseView, earlier: RoomLinks | undefined): RoomLinks;
-export declare function streamedLinks(held: RoomLinks, advanced: StreamedAdvancement): RoomLinks | null;
-//# sourceMappingURL=links.d.ts.map

package/dist/links.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"links.d.ts","sourceRoot":"","sources":["../src/links.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACvD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAOvD,MAAM,MAAM,SAAS,GAAG;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAC5B,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC;IAChD,SAAS,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACxC,CAAC;AAYF,wBAAgB,UAAU,CAAC,KAAK,EAAE,UAAU,GAAG,SAAS,CAWvD;AAOD,wBAAgB,eAAe,CAAC,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,SAAS,GAAG,SAAS,GAAG,SAAS,CAgB1F;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,mBAAmB,GAAG,SAAS,GAAG,IAAI,CAoB9F"}

package/dist/links.js

@@ -1,66 +0,0 @@
-import { roomVersion } from './version.js';
-const ATTACHMENT_REFERENCE = /at_[1-9a-hjkmnp-tv-z][0-9a-hjkmnp-tv-z]*\.[0-9a-hjkmnp-tv-z]/g;
-const NONE = new Set();
-function linkedBy(text) {
-    if (text === null)
-        return NONE;
-    const references = new Set(Array.from(text.matchAll(ATTACHMENT_REFERENCE), ([found]) => found));
-    return references.size === 0 ? NONE : references;
-}
-function handedOf(attachments) {
-    return new Set((attachments ?? []).map((attachment) => attachment.reference));
-}
-export function scopeLinks(scope) {
-    return {
-        roomVersion: roomVersion(scope),
-        handed: handedOf(scope.attachments),
-        paths: new Map(scope.contents.map(({ path, content }) => [path, linkedBy(content)])),
-        revisions: new Map(scope.files.flatMap(({ path, revision }) => revision === undefined ? [] : [[path, revision]])),
-    };
-}
-function revised(revisions, path, revision) {
-    if (revision === undefined)
-        revisions.delete(path);
-    else
-        revisions.set(path, revision);
-}
-export function enumeratedLinks(view, earlier) {
-    const paths = new Map(earlier?.paths);
-    const revisions = new Map(earlier?.revisions);
-    for (const change of view.changes) {
-        paths.set(change.path, linkedBy('content' in change ? change.content : null));
-        revised(revisions, change.path, 'removed' in change
-            ? undefined
-            : 'reference' in change
-                ? change.reference.revision
-                : change.revision);
-    }
-    return { roomVersion: roomVersion(view), handed: handedOf(view.attachments), paths, revisions };
-}
-export function streamedLinks(held, advanced) {
-    const paths = new Map(held.paths);
-    const revisions = new Map(held.revisions);
-    const dropped = new Set();
-    for (const entry of advanced.entries) {
-        revised(revisions, entry.path, entry.kind === 'removed' ? undefined : entry.revision);
-        const text = entry.kind === 'removed' ? null : entry.text;
-        if (text === undefined)
-            return null;
-        const linked = linkedBy(text);
-        for (const reference of linked)
-            if (!held.handed.has(reference))
-                return null;
-        for (const reference of paths.get(entry.path) ?? held.handed) {
-            if (held.handed.has(reference) && !linked.has(reference))
-                dropped.add(reference);
-        }
-        paths.set(entry.path, linked);
-    }
-    for (const references of paths.values()) {
-        for (const reference of references)
-            dropped.delete(reference);
-    }
-    if (dropped.size > 0)
-        return null;
-    return { roomVersion: advanced.page.roomVersion, handed: held.handed, paths, revisions };
-}