@4fu/arbor-interfaces 0.0.0-stage → 0.1.0

package/environment.d.ts

@@ -0,0 +1,109 @@
+/**
+ * The `Environment` interface: skills, MCP servers and services - revisions,
+ * validation, the shared `/env` mount, deltas (docs/architecture.md#interfaces,
+ * docs/environment.md).
+ *
+ * The model changes the environment itself, with `reload`: copy, edit,
+ * validate, replace as a whole, record an environment revision, broadcast the
+ * delta. Each item has its own revision, so changes to different items never
+ * conflict. Two things are outside the model's reach: the value of a secret,
+ * and the built-in skills.
+ *
+ * The settings are an item like any other, at `/env/settings.json`, so the
+ * model changes its own identity, general rules, judge and model tiers the same
+ * way it changes a skill.
+ */
+import type { FunctionSpec } from "./agent.ts";
+import type { EnvItemName, EnvItemRef, EnvRef } from "./refs.ts";
+import type { Settings } from "./settings.ts";
+import type { ArborErrorInfo } from "@4fu/arbor-errors";
+export type EnvItemKind = "skill" | "mcp" | "service" | "settings";
+/** One installed item. */
+export interface EnvItem {
+    ref: EnvItemRef;
+    kind: EnvItemKind;
+    name: string;
+    /** One line: a name, a description and, for a skill, its path. */
+    description: string;
+    /** A skill's path under `/env`. */
+    path?: string;
+    revision: number;
+    time: number;
+    /** True for the built-in skills, which are read-only. */
+    builtin?: boolean;
+    /**
+     * An MCP server's functions, listed when the server was last validated. A
+     * server is a module of its own in code mode, so this is what the catalog
+     * declares and what `tool_search` answers (docs/tools.md#modules).
+     */
+    functions?: readonly FunctionSpec[];
+}
+/**
+ * One draft of an environment item, waiting for `reload`. A window's draft
+ * names a path inside that window's workspace; a plugin's draft names a path on
+ * the host, beside the plugin's own files.
+ */
+export interface EnvDraft {
+    kind: EnvItemKind;
+    name: string;
+    /** Where the draft is: in the window's workspace, or a host path for a plugin. */
+    path: string;
+    /** The revision the draft was copied from; a newer one refuses the install. */
+    copiedFrom?: number;
+}
+export interface EnvValidation {
+    ok: boolean;
+    /** One entry per draft, so a retry acts only on what did not pass. */
+    items: ReadonlyArray<{
+        name: string;
+        ok: boolean;
+        error?: ArborErrorInfo;
+    }>;
+}
+export interface EnvRevision {
+    ref: EnvRef;
+    previous: EnvRef | null;
+    time: number;
+    window: string | null;
+    changes: ReadonlyArray<{
+        change: "added" | "changed" | "removed";
+        item: EnvItem;
+    }>;
+}
+/** What a live window is told changed since it opened. */
+export interface EnvDelta {
+    revision: EnvRef;
+    previous: EnvRef;
+    items: ReadonlyArray<{
+        change: "added" | "changed" | "removed";
+        item: EnvItem;
+    }>;
+}
+export interface Environment {
+    /** The shared mount every window reads `/env` through. */
+    readonly mount: string;
+    /** The directory the mount is, on the host, which the file tools read. */
+    readonly directory: string;
+    revision(): Promise<EnvRef>;
+    list(): Promise<readonly EnvItem[]>;
+    /** An item's revisions, or the environment's when `item` is omitted. */
+    history(item?: EnvItemRef | EnvItemName): Promise<readonly EnvRevision[]>;
+    /** The settings, from `/env/settings.json`. Undefined until one is installed. */
+    settings(): Promise<Settings | undefined>;
+    /** Validate drafts: a skill parses, an MCP server starts and lists its functions. */
+    validate(drafts: readonly EnvDraft[]): Promise<EnvValidation>;
+    /**
+     * `reload({ install, remove })`. Replaces each item as a whole, or refuses
+     * and changes nothing. One call is one environment revision, so a call that
+     * both installs and removes lands as a single delta.
+     */
+    install(drafts: readonly EnvDraft[], remove?: readonly (EnvItemRef | EnvItemName)[]): Promise<EnvRevision>;
+    /** `reload({ remove })`. */
+    remove(items: readonly (EnvItemRef | EnvItemName)[]): Promise<EnvRevision>;
+    /** What changed since a revision, for a live window's delta. */
+    delta(since: EnvRef): Promise<EnvDelta>;
+    /** Start every installed service again, after a host restart. */
+    resume(): Promise<void>;
+    /** Call one function of an installed MCP server, from a script in `code_exec`. */
+    call(server: string, fn: string, args: Record<string, unknown>): Promise<string>;
+}

package/environment.js

@@ -0,0 +1,16 @@
+/**
+ * The `Environment` interface: skills, MCP servers and services - revisions,
+ * validation, the shared `/env` mount, deltas (docs/architecture.md#interfaces,
+ * docs/environment.md).
+ *
+ * The model changes the environment itself, with `reload`: copy, edit,
+ * validate, replace as a whole, record an environment revision, broadcast the
+ * delta. Each item has its own revision, so changes to different items never
+ * conflict. Two things are outside the model's reach: the value of a secret,
+ * and the built-in skills.
+ *
+ * The settings are an item like any other, at `/env/settings.json`, so the
+ * model changes its own identity, general rules, judge and model tiers the same
+ * way it changes a skill.
+ */
+export {};

package/events.d.ts

@@ -0,0 +1,162 @@
+/**
+ * Events and the shapes a `Journal` read returns (docs/journal.md).
+ */
+import type { BlobRef, EventKind, EventRef, ExternalRef, LinkKind, MatchKind, Ref, Target, WindowRef } from "./refs.ts";
+import type { ArborErrorInfo } from "@4fu/arbor-errors";
+/** What an append carries. The journal assigns `ref`, `seq` and, when omitted, `time`. */
+export interface EventInput {
+    kind: EventKind;
+    /** The window that wrote it; empty for an outside event not yet dispatched. */
+    window?: WindowRef | null;
+    body?: string | null;
+    targets?: readonly Target[];
+    refs?: readonly Ref[];
+    /** Links the host recorded. The new event is the `from` side of each. */
+    links?: readonly LinkInput[];
+    /** Native id of an outside message, with a short channel prefix: `qq:12345`. */
+    external?: ExternalRef | null;
+    blobs?: readonly BlobRef[];
+    /** Assigned by the journal when omitted; the journal's clock is the only writer. */
+    time?: number;
+}
+/** One link between refs. */
+export interface Link {
+    kind: LinkKind;
+    from: Ref;
+    to: Ref;
+    /** Relative strength; a bare cite is weaker than a declared link. */
+    weight: number;
+    time: number;
+}
+/** A link an append declares. `from` is the event being appended. */
+export interface LinkInput {
+    kind: LinkKind;
+    /**
+     * The ref it names. A link goes from what names it to what it names, so a
+     * trace walks `from` to `to` back to where something came from.
+     */
+    to: Ref;
+    weight?: number;
+}
+/** A redaction, shown in place of the erased content. */
+export interface Redaction {
+    /** The event that redacted this one. */
+    by: EventRef;
+    reason: string;
+    time: number;
+}
+/** One immutable record. */
+export interface Event {
+    ref: EventRef;
+    /** The event's place in the one global order. Only grows. */
+    seq: number;
+    window: WindowRef | null;
+    time: number;
+    kind: EventKind;
+    targets: Target[];
+    refs: Ref[];
+    links: Link[];
+    external: ExternalRef | null;
+    blobs: BlobRef[];
+    body: string | null;
+    redacted: Redaction | null;
+}
+/** Options for a chronological listing. */
+export interface ListOptions {
+    window?: WindowRef;
+    kinds?: readonly EventKind[];
+    targets?: readonly Target[];
+    external?: string;
+    /** Only events after this sequence number. */
+    afterSeq?: number;
+    beforeSeq?: number;
+    limit?: number;
+    offset?: number;
+}
+/** One page of a read. The bound is reported every time (docs/prompting.md). */
+export interface Page<T> {
+    items: T[];
+    /** How many items match in total, before the page cut. */
+    total: number;
+    limit: number;
+    /** The exact call that pages the rest. */
+    nextCall: string;
+}
+export type EventPage = Page<Event>;
+/** Options for `around`. */
+export interface AroundOptions {
+    before?: number;
+    after?: number;
+}
+/** Options for `search`. */
+export interface SearchOptions {
+    kinds?: readonly EventKind[];
+    targets?: readonly Target[];
+    window?: WindowRef;
+    /** Find the stored copy of an outside message by its native id. */
+    external?: string;
+    afterSeq?: number;
+    beforeSeq?: number;
+    limit?: number;
+    offset?: number;
+}
+/** One search hit: its ref and window, plus what matched. */
+export interface SearchHit {
+    ref: EventRef;
+    seq: number;
+    window: WindowRef | null;
+    kind: EventKind;
+    time: number;
+    match: MatchKind;
+    /** Relevance in 0..1 within its index; higher is better. */
+    score: number;
+    /** The event's opening words, for a one-line result. */
+    summary: string;
+}
+export type SearchPage = Page<SearchHit>;
+/** Options for `links`. */
+export interface LinksOptions {
+    offset?: number;
+    limit?: number;
+}
+/** One related item, by weight. */
+export interface RelatedItem {
+    ref: Ref;
+    kind: LinkKind;
+    weight: number;
+    direction: "out" | "in";
+    window: WindowRef | null;
+    time: number;
+    summary: string;
+}
+export type LinkPage = Page<RelatedItem>;
+/** Options for `trace`. */
+export interface TraceOptions {
+    /** How many steps back from the traced ref. */
+    maxHops?: number;
+    /** How many nodes the walk may visit. */
+    maxNodes?: number;
+}
+/** One node of a trace: where a ref came from, back to the original input. */
+export interface TraceNode {
+    ref: Ref;
+    kind?: EventKind;
+    window: WindowRef | null;
+    time: number;
+    summary: string;
+    /** True at an outside message, or at a ref the walk stopped on. */
+    origin: boolean;
+    from: TraceNode[];
+}
+/** A target a window is behind on. */
+export interface TargetGap {
+    target: Target;
+    /** The newest event on the target. */
+    latest: number;
+    /** The newest event on the target the window has seen. */
+    watermark: number;
+    /** How many events the window has not seen. */
+    count: number;
+}
+/** One refusal a `Journal` returns, in the core's error shape. */
+export type JournalError = ArborErrorInfo;

package/events.js

@@ -0,0 +1,4 @@
+/**
+ * Events and the shapes a `Journal` read returns (docs/journal.md).
+ */
+export {};

package/hooks.d.ts

@@ -0,0 +1,141 @@
+/**
+ * Hooks: how a deployment or a plugin adds policy without replacing a module
+ * (docs/architecture.md#hooks).
+ *
+ * The framework sets no policy of its own. Each hook can observe, change or
+ * refuse, and refuses in the core's error shape, so the model always reads the
+ * same kind of refusal. Permissions, privacy review, budgets and approvals are
+ * built from these.
+ */
+import type { ArborErrorInfo } from "@4fu/arbor-errors";
+import type { Delivery, RenderedPrompt, ToolCall, ToolResult } from "./agent.ts";
+import type { Block } from "./blocks.ts";
+import type { Event, EventInput } from "./events.ts";
+import type { Effect } from "./effects.ts";
+import type { EnvDraft, EnvRevision } from "./environment.ts";
+import type { JudgeAnswer, JudgeRequest } from "./judge.ts";
+import type { NoteWriteInput } from "./notes.ts";
+import type { TaskInput } from "./task.ts";
+import type { ServiceStatus } from "./supervisor.ts";
+import type { WindowRef } from "./refs.ts";
+import type { Handoff } from "./windows.ts";
+/** What a hook answers. `context` carries what it changed. */
+export type HookOutcome<T> = {
+    allow: true;
+    context?: T;
+} | {
+    allow: false;
+    error: ArborErrorInfo;
+};
+export interface AppendContext {
+    input: EventInput;
+    event?: Event;
+}
+export interface DispatchContext {
+    task: TaskInput;
+    /** The judge's answer, when the judge decided. */
+    answer?: JudgeAnswer;
+    /** The window the task went to, or `null` when a new window opens. */
+    window?: WindowRef | null;
+}
+export interface JudgeContext {
+    request: JudgeRequest;
+    answer?: JudgeAnswer;
+    /** The state the judge saw, after scrubbing. */
+    scrubbed?: boolean;
+}
+export interface WindowStartContext {
+    window: WindowRef;
+    task: TaskInput;
+    continuation?: {
+        previous: WindowRef;
+        handoff?: Handoff;
+    };
+}
+export interface WindowEndContext {
+    window: WindowRef;
+    handoff?: Handoff;
+    reason: string;
+}
+export interface WindowContinueContext {
+    window: WindowRef;
+    previous: WindowRef;
+    handoff?: Handoff;
+    /** Set after the hard limit: the window was reset mid-task. */
+    midTaskReset?: boolean;
+}
+export interface ModelRequestContext {
+    window: WindowRef;
+    prompt: RenderedPrompt;
+    inputs: readonly Block[];
+}
+export interface DeliveryContext {
+    window: WindowRef;
+    delivery: Delivery;
+}
+export interface ToolCallContext {
+    window: WindowRef;
+    call: ToolCall;
+    result?: ToolResult;
+}
+/** What `beforeEffect` answers: release, hold for approval, or drop. */
+export type EffectOutcome = {
+    action: "release";
+} | {
+    action: "hold";
+    approval?: string;
+} | {
+    action: "drop";
+    error: ArborErrorInfo;
+};
+/** An effect the host holds until an approval releases or drops it. */
+export interface EffectHold {
+    effect: Effect;
+    release(): Promise<void>;
+    drop(reason: string): Promise<void>;
+}
+export interface EffectContext {
+    effect: Effect;
+    /** The executor that owns it. */
+    executor?: string;
+}
+export interface NoteWriteContext {
+    window: WindowRef;
+    input: NoteWriteInput;
+    /** The revision that was written, for `afterNoteWrite`. */
+    revision?: number;
+}
+export interface ReloadContext {
+    window: WindowRef;
+    drafts: readonly EnvDraft[];
+    remove?: readonly string[];
+    revision?: EnvRevision;
+}
+export interface ServiceStateContext {
+    service: string;
+    status: ServiceStatus;
+}
+export interface Hooks {
+    beforeAppend?(context: AppendContext): Promise<HookOutcome<AppendContext>> | HookOutcome<AppendContext>;
+    afterAppend?(context: AppendContext): Promise<void> | void;
+    beforeDispatch?(context: DispatchContext): Promise<HookOutcome<DispatchContext>> | HookOutcome<DispatchContext>;
+    afterDispatch?(context: DispatchContext): Promise<void> | void;
+    beforeJudge?(context: JudgeContext): Promise<HookOutcome<JudgeContext>> | HookOutcome<JudgeContext>;
+    afterJudge?(context: JudgeContext): Promise<void> | void;
+    windowStart?(context: WindowStartContext): Promise<HookOutcome<WindowStartContext>> | HookOutcome<WindowStartContext>;
+    windowEnd?(context: WindowEndContext): Promise<HookOutcome<WindowEndContext>> | HookOutcome<WindowEndContext>;
+    windowContinue?(context: WindowContinueContext): Promise<HookOutcome<WindowContinueContext>> | HookOutcome<WindowContinueContext>;
+    beforeModelRequest?(context: ModelRequestContext): Promise<HookOutcome<ModelRequestContext>> | HookOutcome<ModelRequestContext>;
+    beforeDelivery?(context: DeliveryContext): Promise<HookOutcome<DeliveryContext>> | HookOutcome<DeliveryContext>;
+    beforeToolCall?(context: ToolCallContext): Promise<HookOutcome<ToolCallContext>> | HookOutcome<ToolCallContext>;
+    afterToolCall?(context: ToolCallContext): Promise<void> | void;
+    beforeEffect?(context: EffectContext): Promise<EffectOutcome> | EffectOutcome;
+    beforeNoteWrite?(context: NoteWriteContext): Promise<HookOutcome<NoteWriteContext>> | HookOutcome<NoteWriteContext>;
+    afterNoteWrite?(context: NoteWriteContext): Promise<void> | void;
+    beforeReload?(context: ReloadContext): Promise<HookOutcome<ReloadContext>> | HookOutcome<ReloadContext>;
+    afterReload?(context: ReloadContext): Promise<void> | void;
+    serviceStateChange?(context: ServiceStateContext): Promise<void> | void;
+}
+/** A held effect, for an approval surface built on `beforeEffect`. */
+export interface HeldEffect extends EffectHold {
+}

package/hooks.js

@@ -0,0 +1,10 @@
+/**
+ * Hooks: how a deployment or a plugin adds policy without replacing a module
+ * (docs/architecture.md#hooks).
+ *
+ * The framework sets no policy of its own. Each hook can observe, change or
+ * refuse, and refuses in the core's error shape, so the model always reads the
+ * same kind of refusal. Permissions, privacy review, budgets and approvals are
+ * built from these.
+ */
+export {};

package/index.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @4fu/arbor-interfaces - every replaceable interface, and the core's own shapes.
+ *
+ * No pi type or SQL row crosses an interface; the core only sees
+ * its own shapes (docs/architecture.md#interfaces). Each interface ships with
+ * a default; replacing a module means implementing its interface and
+ * registering it, and nothing else changes.
+ */
+export type { EventRef, WindowRef, NoteId, NoteRef, TaskRef, MessageRef, WorkspaceRef, EnvRef, EnvItemRef, EnvItemName, BlobRef, ExternalRef, Ref, Target, EventKind, LinkKind, MatchKind, } from "./refs.ts";
+export type { BlockValue, Block, BlockKind, BlockFieldSpec, BlockKindSpec, TextTable, } from "./blocks.ts";
+/** Page bounds every read reports (docs/prompting.md). */
+export { DEFAULT_PAGE_LIMIT, MAX_PAGE_LIMIT } from "./refs.ts";
+export type { EventInput, Link, LinkInput, Redaction, Event, ListOptions, Page, EventPage, AroundOptions, SearchOptions, SearchHit, SearchPage, LinksOptions, RelatedItem, LinkPage, TraceOptions, TraceNode, TargetGap, JournalError, } from "./events.ts";
+export type { BlobInput, BlobContent, BlobInfo, BlobStore, Segmenter, Journal, } from "./journal.ts";
+export type { ModelInfo, LoginState, LoginRequest, LoginResult, RenderedPrompt, OpenWindowRequest, WindowLimits, ContinuationInfo, Delivery, WindowSession, WindowEvent, WindowEndReason, WindowOutcome, AgentBackend, DirectToolSpec, ModuleSpec, FunctionSpec, ParameterSpec, ToolCall, ToolResult, } from "./agent.ts";
+export type { WindowState, WindowRuntimeState, TokenUsage, Handoff, BoardLine, Expectation, InputBlock, } from "./windows.ts";
+export type { NoteStatus, Anchor, NoteWriteInput, Note, NoteSummary, NoteBody, NoteRevision, NoteContext, NoteQuery, NoteConflictInfo, ActiveSetBudget, ActiveCandidate, NoteUseKind, NoteUseInput, SnapshotOptions, NotesSnapshot, NoteDelta, NoteDeltaItem, NoteStore, } from "./notes.ts";
+export type { ExecResult, StagedFile, WorkspaceMount, WorkspaceQuota, Workspace, } from "./workspace.ts";
+export type { JudgeMode, JudgeDecisionKind, CandidateWindow, JudgeTask, FilterState, RouteState, ModelTierState, NoticeState, BroadcastState, ActiveSetState, FilterRequest, RouteRequest, ModelTierRequest, NoticeRequest, BroadcastRequest, ActiveSetRequest, JudgeRequest, FilterAnswer, RouteScore, RouteAnswer, ModelTierAnswer, WindowDecision, NoticeAnswer, BroadcastAnswer, ActiveSetAnswer, JudgeAnswer, Judge, JudgeCriteria, } from "./judge.ts";
+export type { OutsideEvent, OutsideMessage, ChannelConnection, SendRequest, SendResult, Unsubscribe, Channel, } from "./channel.ts";
+export type { TaskKind, TaskInput, Task, TaskSource } from "./task.ts";
+export type { EffectKind, Effect, EffectResult, EffectExecutor } from "./effects.ts";
+export type { CallContext, ToolGroup } from "./tools.ts";
+export type { EnvItemKind, EnvItem, EnvDraft, EnvValidation, EnvRevision, EnvDelta, Environment, } from "./environment.ts";
+export type { ServiceState, ServiceSpec, ServiceHandle, ServiceStatus, LogOptions, LogPage, Supervisor, } from "./supervisor.ts";
+export type { QueuedInput, InsertionRequest, InsertionPlan, RateLimitState, AdmissionRequest, AdmissionPlan, SkipPeriod, ScheduledTaskInput, ScheduledTask, ScheduledTaskUpdate, Scheduler, } from "./scheduler.ts";
+export type { HookOutcome, AppendContext, DispatchContext, JudgeContext, WindowStartContext, WindowEndContext, WindowContinueContext, ModelRequestContext, DeliveryContext, ToolCallContext, EffectOutcome, EffectHold, EffectContext, NoteWriteContext, ReloadContext, ServiceStateContext, Hooks, HeldEffect, } from "./hooks.ts";
+export type { PluginAdapters, PromptSection, Plugin, } from "./plugin.ts";
+export type { Settings } from "./settings.ts";

package/index.js

@@ -0,0 +1,10 @@
+/**
+ * @4fu/arbor-interfaces - every replaceable interface, and the core's own shapes.
+ *
+ * No pi type or SQL row crosses an interface; the core only sees
+ * its own shapes (docs/architecture.md#interfaces). Each interface ships with
+ * a default; replacing a module means implementing its interface and
+ * registering it, and nothing else changes.
+ */
+/** Page bounds every read reports (docs/prompting.md). */
+export { DEFAULT_PAGE_LIMIT, MAX_PAGE_LIMIT } from "./refs.js";

package/journal.d.ts

@@ -0,0 +1,87 @@
+/**
+ * The `Journal` interface: the one append-only record, shared live by every
+ * window (docs/journal.md).
+ *
+ * Rules an implementation must keep:
+ *
+ * - Append-only. Nothing is edited, nothing is deleted, nothing merges. The one
+ *   exception is a redaction, which erases content and records that it did.
+ * - One global order. `seq` is assigned at append and only grows; watermarks
+ *   and every comparison use it. `time` is for display only.
+ * - An outside message keeps its native id in `external`, with a unique index,
+ *   so a redelivered message is stored once.
+ * - Visible as soon as it is written.
+ * - Every refusal is an `ArborError` in the core's shape.
+ */
+import type { AroundOptions, Event, EventInput, EventPage, LinkPage, LinksOptions, ListOptions, SearchOptions, SearchPage, TargetGap, TraceNode, TraceOptions } from "./events.ts";
+import type { BlobRef, EventRef, Ref, Target, WindowRef } from "./refs.ts";
+/** Content a blob store takes. */
+export interface BlobInput {
+    data: Uint8Array | string;
+    mime?: string;
+}
+/** Content a blob store returns. */
+export interface BlobContent {
+    data: Uint8Array;
+    mime?: string;
+}
+export interface BlobInfo {
+    ref: BlobRef;
+    size: number;
+    mime?: string;
+    time: number;
+}
+/**
+ * Media and files are stored once by content beside the journal; events hold
+ * their refs (docs/journal.md#media). The journal never keeps the bytes.
+ */
+export interface BlobStore {
+    put(input: BlobInput): Promise<BlobRef>;
+    get(ref: BlobRef): Promise<BlobContent | null>;
+    has(ref: BlobRef): Promise<boolean>;
+    stat(ref: BlobRef): Promise<BlobInfo | null>;
+    delete(ref: BlobRef): Promise<void>;
+}
+/**
+ * Word segmentation for the word index. The default is jieba's dictionary
+ * segmentation when `@4fu/arbor-segmenter-jieba` is installed, and the
+ * per-character-and-bigram approximation when it is not
+ * (docs/journal.md#search); a deployment replaces either by implementing this
+ * and registering it.
+ */
+export interface Segmenter {
+    segment(text: string): string[];
+}
+export interface Journal {
+    /** Append one event. Assigns `ref` and `seq`; a redelivered `external` id is stored once. */
+    append(input: EventInput): Promise<Event>;
+    /** Read one event by its ref, or `null`. */
+    get(ref: EventRef): Promise<Event | null>;
+    /** Read several events by ref, in the order asked for. Missing refs are skipped. */
+    getMany(refs: readonly EventRef[]): Promise<Event[]>;
+    /** List events chronologically, filtered. */
+    list(options?: ListOptions): Promise<EventPage>;
+    /** The events around one, in the global order. */
+    around(ref: EventRef, options?: AroundOptions): Promise<Event[]>;
+    /** Lexical search: exact substring hits first, then word hits, each with its ref and window. */
+    search(query: string, options?: SearchOptions): Promise<SearchPage>;
+    /** Related items by weight, with the call that pages the rest. */
+    links(ref: Ref, options?: LinksOptions): Promise<LinkPage>;
+    /** Walk the links back from any ref to where it came from. */
+    trace(ref: Ref, options?: TraceOptions): Promise<TraceNode>;
+    /** The newest event on a target a window has seen, or `null`. */
+    watermark(window: WindowRef, target: Target): Promise<number | null>;
+    /** Move a window's watermark forward. Never moves it back. */
+    advanceWatermark(window: WindowRef, target: Target, seq: number): Promise<number>;
+    /** The targets a window touched that have events it has not seen. */
+    targetsBehind(window: WindowRef): Promise<TargetGap[]>;
+    /**
+     * Erase the content of one event and record that it was erased. Every ref to
+     * it keeps working and shows the redaction and the event that made it.
+     */
+    redact(ref: EventRef, reason: string): Promise<Event>;
+    /** Media and files stored beside the journal. */
+    readonly blobs: BlobStore;
+    /** Release the underlying store. */
+    close(): Promise<void>;
+}

package/journal.js

@@ -0,0 +1,16 @@
+/**
+ * The `Journal` interface: the one append-only record, shared live by every
+ * window (docs/journal.md).
+ *
+ * Rules an implementation must keep:
+ *
+ * - Append-only. Nothing is edited, nothing is deleted, nothing merges. The one
+ *   exception is a redaction, which erases content and records that it did.
+ * - One global order. `seq` is assigned at append and only grows; watermarks
+ *   and every comparison use it. `time` is for display only.
+ * - An outside message keeps its native id in `external`, with a unique index,
+ *   so a redelivered message is stored once.
+ * - Visible as soon as it is written.
+ * - Every refusal is an `ArborError` in the core's shape.
+ */
+export {};