@anchrd/intel-api 0.3.0 → 0.3.2

package/dist/flows/flows.types.d.ts

@@ -1,25 +1,84 @@
-import type { CompleteFlowRunStepInput, CreateFlowInput, Flow, FlowDocument, FlowGraph, FlowRun, FlowRunStep, FlowVersion, PublishFlowInput, ResourceGrant, RevokeFlowGrantInput, SaveFlowVersionInput, ShareFlowInput, StartFlowRunInput } from "@anchrd/intel-contract";
+import type { CompleteFlowRunStepInput, CreateFlowInput, Flow, FlowDocument, FlowGraph, FlowPublishPreview, FlowRequirements, FlowRun, FlowRunHistory, FlowRunList, FlowRunStep, FlowVersion, KnowledgeNode, ListFlowRunsInput, ListFlowsInput, PreviewFlowPublishInput, PublishFlowInput, RelationGraph, RelationGraphInput, ResourceVerb, SaveFlowVersionInput, StartFlowRunInput, UpdateFlowInput } from "@anchrd/intel-contract";
+export type FlowPrincipal = Pick<FlowActor, "id" | "email" | "isAdmin">;
+export type FlowCallReach = "subtree" | "library" | "out-of-reach";
+export interface FlowRunChainEntry {
+    runId: string;
+    flowId: string;
+    flowTitle: string;
+    versionId: string;
+    parentRunId: string | null;
+    currentNodeId: string | null;
+}
+export interface ListRunsQuery {
+    flowId: string;
+    failedOnly: boolean;
+    limit: number;
+    cursor: {
+        createdAt: string;
+        id: string;
+    } | null;
+}
+export interface FlowCallSite {
+    runId: string;
+    nodeId: string;
+}
+export interface FlowVisibleCall extends FlowCallSite {
+    calledRunId: string;
+}
+export interface FlowRunStepRow {
+    runId: string;
+    nodeId: string;
+    outcome: "completed" | "failed";
+    branch: string | null;
+    error: string | null;
+    completedAt: string;
+}
 export interface FlowActor {
     id: string;
     email: string;
     canRun: boolean;
     canApprove: boolean;
+    isAdmin?: boolean;
+}
+export type FlowVerb = Extract<ResourceVerb, "read" | "write" | "execute">;
+export type FlowOperation = "flows.create" | "flows.update" | "flows.save" | "flows.publish" | "flows.run" | "flows.complete";
+export interface BoundedLevel<T> {
+    items: T[];
+    total: number;
 }
-export type FlowOperation = "flows.create" | "flows.save" | "flows.publish" | "flows.run" | "flows.complete" | "flows.share" | "flows.revoke";
 export interface FlowRepository {
-    listVisible(actor: FlowActor): Promise<Flow[]>;
+    listVisible(actor: FlowActor, input?: ListFlowsInput): Promise<Flow[]>;
+    listVisibleBounded(actor: FlowActor, folderId: string | null, limit: number): Promise<BoundedLevel<Flow>>;
     getVisible(actor: FlowActor, flowId: string): Promise<Flow | null>;
-    canEdit(actor: FlowActor, flowId: string): Promise<boolean>;
-    canManage(actor: FlowActor, flowId: string): Promise<boolean>;
+    can(actor: FlowActor, flowId: string, verb: FlowVerb): Promise<boolean>;
+    getCallable(actor: FlowActor, flowId: string): Promise<Flow | null>;
+    listCallable(actor: FlowActor, flowIds: string[]): Promise<Flow[]>;
+    callReach(callerFolderId: string | null, calleeFolderId: string | null): Promise<FlowCallReach>;
+    externalCallers(actor: FlowPrincipal, folderId: string): Promise<{
+        visible: string[];
+        hidden: number;
+    }>;
+    knowledgeReferences(actor: FlowPrincipal, folderId: string): Promise<string[]>;
+    publishedCallees(flowId: string): Promise<{
+        title: string;
+        calleeIds: string[];
+    } | null>;
     findIdempotent(actorId: string, operation: FlowOperation, key: string): Promise<string | null>;
-    findIdempotentRevocation(actorId: string, key: string): Promise<boolean | null>;
     insertFlow(input: {
         flow: Flow;
         actorId: string;
         idempotencyKey: string;
         auditId: string;
     }): Promise<Flow>;
+    updateFlow(input: {
+        flow: Flow;
+        baseUpdatedAt: string;
+        actorId: string;
+        idempotencyKey: string;
+        auditId: string;
+    }): Promise<"conflict" | Flow>;
     getVersion(versionId: string): Promise<FlowVersion | null>;
+    getVersions(versionIds: string[]): Promise<FlowVersion[]>;
     insertVersion(input: {
         version: FlowVersion;
         baseVersionId: string | null;
@@ -35,21 +94,6 @@ export interface FlowRepository {
         auditId: string;
         occurredAt: string;
     }): Promise<boolean>;
-    listGrants(flowId: string): Promise<ResourceGrant[]>;
-    setGrant(input: {
-        grant: ResourceGrant;
-        actorId: string;
-        idempotencyKey: string;
-        auditId: string;
-    }): Promise<ResourceGrant>;
-    revokeGrant(input: {
-        flowId: string;
-        grantId: string;
-        actorId: string;
-        idempotencyKey: string;
-        auditId: string;
-        occurredAt: string;
-    }): Promise<boolean>;
     insertRun(input: {
         run: FlowRun;
         actorId: string;
@@ -57,6 +101,12 @@ export interface FlowRepository {
         auditId: string;
     }): Promise<FlowRun>;
     getRunVisible(actor: FlowActor, runId: string): Promise<FlowRun | null>;
+    listRunsVisible(actor: FlowActor, input: ListRunsQuery): Promise<FlowRun[]>;
+    failedSteps(runIds: string[]): Promise<FlowRunStepRow[]>;
+    runSteps(runId: string): Promise<FlowRunStepRow[]>;
+    visibleCallRuns(actor: FlowActor, sites: FlowCallSite[]): Promise<FlowVisibleCall[]>;
+    findChildRun(parentRunId: string, parentNodeId: string): Promise<FlowRun | null>;
+    runChain(runId: string): Promise<FlowRunChainEntry[]>;
     advanceRun(input: {
         run: FlowRun;
         expectedNodeId: string;
@@ -79,28 +129,52 @@ export interface FlowDeps {
     runtime: FlowRuntime;
     id(): string;
     now(): Date;
-    knowledgeExists(actor: FlowActor, resourceId: string): Promise<boolean>;
+    folderAccess(actor: FlowActor, folderId: string): Promise<FolderAccess>;
+    /**
+     * The children of one folder of the shared tree as this actor may see them, without their bodies.
+     * `null` is the root. Knowledge answers, for the same reason `folderAccess` does.
+     *
+     * ⚠️ `limit` bounds the read, not its result: its one caller draws a bounded picture, and a folder
+     * of a thousand documents must not be loaded whole for it (#30). What the bound left behind comes
+     * back as `total`, counted among the nodes this actor may see and no others — a number that
+     * included the rest would say that the rest is there.
+     */
+    knowledgeChildren(actor: FlowActor, folderId: string | null, limit: number): Promise<BoundedLevel<KnowledgeNode>>;
+    /**
+     * One node as this actor may see it. `null` means "this actor cannot reach it", never "it is
+     * gone" — the relation graph must then leave it out altogether rather than draw a placeholder,
+     * because the edge alone would already give away that it exists (#19).
+     *
+     * ⚠️ Three jobs, one door, on purpose. The relation graph draws what comes back here; the
+     * requirements list names it; and every Knowledge step of every run is authorized by it, nested
+     * calls included (ADR-0004 §4). A second lookup beside it is how a drawing or a message ends up
+     * kinder than the door it describes — which is what #17 and #19 were sent back for.
+     */
+    visibleKnowledge(actor: FlowActor, nodeId: string): Promise<KnowledgeNode | null>;
     toolFingerprint(actor: FlowActor, toolName: string): Promise<string | null>;
     unavailableTools(actor: FlowActor, toolNames: string[]): Promise<string[]>;
 }
+export type FolderAccess = "ok" | "missing" | "not-a-folder" | "forbidden";
 export interface FlowService {
-    list(actor: FlowActor): Promise<{
+    list(actor: FlowActor, input?: ListFlowsInput): Promise<{
         items: Flow[];
     }>;
     get(actor: FlowActor, flowId: string): Promise<FlowDocument>;
+    listCalls(actor: FlowActor, flowId: string): Promise<{
+        items: Flow[];
+    }>;
+    relationGraph(actor: FlowActor, input: RelationGraphInput): Promise<RelationGraph>;
+    listRequirements(actor: FlowActor, flowId: string): Promise<FlowRequirements>;
     create(actor: FlowActor, input: CreateFlowInput): Promise<Flow>;
+    update(actor: FlowActor, input: UpdateFlowInput): Promise<Flow>;
     save(actor: FlowActor, input: SaveFlowVersionInput): Promise<FlowDocument>;
+    previewPublish(actor: FlowActor, input: PreviewFlowPublishInput): Promise<FlowPublishPreview>;
     publish(actor: FlowActor, input: PublishFlowInput): Promise<Flow>;
     start(actor: FlowActor, input: StartFlowRunInput): Promise<FlowRunStep>;
     getRun(actor: FlowActor, runId: string): Promise<FlowRunStep>;
+    listRuns(actor: FlowActor, input: ListFlowRunsInput): Promise<FlowRunList>;
+    listRunSteps(actor: FlowActor, runId: string): Promise<FlowRunHistory>;
     completeStep(actor: FlowActor, input: CompleteFlowRunStepInput): Promise<FlowRunStep>;
-    listGrants(actor: FlowActor, flowId: string): Promise<{
-        items: ResourceGrant[];
-    }>;
-    share(actor: FlowActor, input: ShareFlowInput): Promise<ResourceGrant>;
-    revokeGrant(actor: FlowActor, input: RevokeFlowGrantInput): Promise<{
-        revoked: boolean;
-    }>;
 }
 export interface CompiledFlow {
     graph: FlowGraph;

package/dist/http/http.js

@@ -1,21 +1,39 @@
-import { ArchiveKnowledgeNodeInput, CompleteFlowRunStepInput, CreateFlowInput, CreateKnowledgeLinkInput, CreateKnowledgeNodeInput, DeleteKnowledgeLinkInput, ExecuteToolInput, KnowledgeGraphInput, ListKnowledgeNodesInput, PublishFlowInput, RevokeFlowGrantInput, RevokeKnowledgeGrantInput, SaveFlowVersionInput, SaveKnowledgeAttachmentInput, SaveKnowledgeVersionInput, SearchKnowledgeInput, ShareFlowInput, ShareKnowledgeInput, StartFlowRunInput, TestToolInput, UpdateKnowledgeNodeInput, } from "@anchrd/intel-contract";
+import { AppendKnowledgeTableRowsInput, ArchiveKnowledgeNodeInput, CompleteFlowRunStepInput, CreateFlowInput, CreateKnowledgeNodeInput, DefineKnowledgeTableInput, ExecuteToolInput, GetFlowInput, GetFlowRunInput, KnowledgeGraphInput, ListFlowRunsInput, ListFlowsInput, ListKnowledgeNodesInput, PreviewFlowPublishInput, PublishFlowInput, RelationGraphInput, ResolveKnowledgeLinksInput, RevokeKnowledgeGrantInput, SaveFlowVersionInput, SaveKnowledgeAttachmentInput, SaveKnowledgeVersionInput, SearchKnowledgeInput, ShareKnowledgeInput, StartFlowRunInput, TestToolInput, UpdateFlowInput, UpdateKnowledgeNodeInput, } from "@anchrd/intel-contract";
 import { Hono } from "hono";
 import { z } from "zod";
-import { authorizeBearer, bearer } from "../shared/gate-authorization/gate-authorization.js";
+import { authorizeBearer, bearer, permits, } from "../shared/gate-authorization/gate-authorization.js";
 import { IntelError } from "../shared/intel-error/intel-error.js";
 import { problemDetails as problem } from "../shared/problem-details/problem-details.js";
+// A query string is a door to the outside like a body is, so what arrives through it is closed
+// rather than tolerated: `z.strictObject` refuses an unknown field, and this is that refusal for the
+// half of the input Zod never sees. A silently ignored parameter is how a caller believes it asked
+// for something it did not get — a mistyped `limit=` that quietly draws everything, for instance.
+//
+// ⚠️ Not the same decision as `selectionSearch` in the UI, which deliberately passes unknown search
+// parameters through so the portal's return marker survives a redirect. That is a browser location;
+// this is an API route.
+function requireKnownQuery(url, allowed) {
+    const unknown = [];
+    url.searchParams.forEach((_value, key) => {
+        if (!allowed.includes(key))
+            unknown.push(key);
+    });
+    if (unknown.length) {
+        throw new IntelError(400, "invalid_request", `Unknown query parameters: ${unknown.join(", ")}`);
+    }
+}
 function asActor(authorization) {
     return {
         id: authorization.identity.id,
         email: authorization.identity.email,
-        canReindex: authorization.can("intel", "admin"),
+        isAdmin: authorization.can("intel", "admin"),
     };
 }
 function asToolActor(authorization) {
     return {
         id: authorization.identity.id,
         email: authorization.identity.email,
-        canExecute: authorization.can("tools", "execute"),
+        canExecute: permits(authorization, "tools", "execute"),
     };
 }
 // RFC 5987 ext-value: encodeURIComponent leaves ' * ! ( ) unescaped, and a bare apostrophe is a
@@ -29,8 +47,9 @@ function asFlowActor(authorization) {
     return {
         id: authorization.identity.id,
         email: authorization.identity.email,
-        canRun: authorization.can("flows", "run"),
-        canApprove: authorization.can("flows", "approve"),
+        canRun: permits(authorization, "flows", "run"),
+        canApprove: permits(authorization, "flows", "approve"),
+        isAdmin: authorization.can("intel", "admin"),
     };
 }
 export function createHttp(deps) {
@@ -59,11 +78,21 @@ export function createHttp(deps) {
     });
     function requireCapability(context, handle, fn) {
         const authorization = context.get("authorization");
-        if (!authorization.can(handle, fn)) {
+        if (!permits(authorization, handle, fn)) {
             throw new IntelError(403, "permission_required", "Permission required");
         }
         return authorization;
     }
+    // The caller's own identity, so the shell can name who is signed in. It needs no capability —
+    // the answer is the token's own subject — and it returns nothing but id, email, and name.
+    app.get("/session", (context) => {
+        const { identity } = context.get("authorization");
+        return context.json({
+            id: identity.id,
+            email: identity.email,
+            name: identity.name ?? null,
+        });
+    });
     app.get("/knowledge", async (context) => {
         const auth = requireCapability(context, "knowledge", "read");
         const url = new URL(context.req.url);
@@ -109,10 +138,44 @@ export function createHttp(deps) {
             },
         });
     });
+    app.get("/knowledge/:nodeId/table", async (context) => {
+        const auth = requireCapability(context, "knowledge", "read");
+        return context.json(await deps.knowledge.getTable(asActor(auth), context.req.param("nodeId")));
+    });
+    // Defining the header and appending rows are two routes because they are two decisions: the
+    // header is written once and is the contract, an append is the everyday write (#40).
+    app.post("/knowledge/:nodeId/table", async (context) => {
+        const auth = requireCapability(context, "knowledge", "write");
+        const input = DefineKnowledgeTableInput.parse(await context.req.json().catch(() => null));
+        if (input.nodeId !== context.req.param("nodeId")) {
+            throw new IntelError(400, "node_id_mismatch", "Path and body node IDs differ");
+        }
+        return context.json(await deps.knowledge.defineTable(asActor(auth), input), 201);
+    });
+    app.post("/knowledge/:nodeId/table/rows", async (context) => {
+        const auth = requireCapability(context, "knowledge", "write");
+        const input = AppendKnowledgeTableRowsInput.parse(await context.req.json().catch(() => null));
+        if (input.nodeId !== context.req.param("nodeId")) {
+            throw new IntelError(400, "node_id_mismatch", "Path and body node IDs differ");
+        }
+        return context.json(await deps.knowledge.appendTableRows(asActor(auth), input), 201);
+    });
     app.get("/knowledge/:nodeId/links", async (context) => {
         const auth = requireCapability(context, "knowledge", "read");
         return context.json(await deps.knowledge.listLinks(asActor(auth), context.req.param("nodeId")));
     });
+    // A document link's name, for whoever is reading the text (#41). A POST because the list of IDs
+    // is the request body — putting them in a query string would put the tree's identifiers into
+    // logs and referrers. `knowledge/read` and nothing more: it answers with what this reader may
+    // already see, and stays silent about the rest rather than saying that there is a rest.
+    //
+    // There is no route to create or delete a link any more. A relationship is written where it is
+    // meant, in the text, and `POST /knowledge/:nodeId/versions` is what records it.
+    app.post("/knowledge/links/resolve", async (context) => {
+        const auth = requireCapability(context, "knowledge", "read");
+        const input = ResolveKnowledgeLinksInput.parse(await context.req.json().catch(() => null));
+        return context.json(await deps.knowledge.resolveLinks(asActor(auth), input));
+    });
     app.post("/knowledge/search", async (context) => {
         const auth = requireCapability(context, "knowledge", "read");
         const input = SearchKnowledgeInput.parse(await context.req.json().catch(() => null));
@@ -160,23 +223,6 @@ export function createHttp(deps) {
         }
         return context.json(await deps.knowledge.archive(asActor(auth), input));
     });
-    app.post("/knowledge/:nodeId/links", async (context) => {
-        const auth = requireCapability(context, "knowledge", "write");
-        const input = CreateKnowledgeLinkInput.parse(await context.req.json().catch(() => null));
-        if (input.sourceNodeId !== context.req.param("nodeId")) {
-            throw new IntelError(400, "node_id_mismatch", "Path and body source node IDs differ");
-        }
-        return context.json(await deps.knowledge.createLink(asActor(auth), input), 201);
-    });
-    app.post("/knowledge/:nodeId/links/:linkId/revoke", async (context) => {
-        const auth = requireCapability(context, "knowledge", "write");
-        const input = DeleteKnowledgeLinkInput.parse(await context.req.json().catch(() => null));
-        if (input.sourceNodeId !== context.req.param("nodeId") ||
-            input.linkId !== context.req.param("linkId")) {
-            throw new IntelError(400, "link_id_mismatch", "Path and body Knowledge link IDs differ");
-        }
-        return context.json(await deps.knowledge.deleteLink(asActor(auth), input));
-    });
     app.get("/knowledge/:nodeId/grants", async (context) => {
         const auth = requireCapability(context, "knowledge", "share");
         return context.json(await deps.knowledge.listGrants(asActor(auth), context.req.param("nodeId")));
@@ -200,38 +246,66 @@ export function createHttp(deps) {
     });
     app.get("/flows", async (context) => {
         const auth = requireCapability(context, "flows", "read");
-        return context.json(await deps.flows.list(asFlowActor(auth)));
+        const url = new URL(context.req.url);
+        requireKnownQuery(url, ["parentId"]);
+        // Absent means "every flow I may see"; present but empty means the root of the shared tree.
+        // Without that distinction a tree level and a full list would be the same request.
+        const parentId = url.searchParams.get("parentId");
+        const input = ListFlowsInput.parse(url.searchParams.has("parentId") ? { parentId: parentId === "" ? null : parentId } : {});
+        return context.json(await deps.flows.list(asFlowActor(auth), input));
+    });
+    // ⚠️ Before `/flows/:flowId`, or the router would read "graph" as a flow ID. Same order and same
+    // reason as `/knowledge/graph`.
+    app.get("/flows/graph", async (context) => {
+        const auth = requireCapability(context, "flows", "read");
+        const url = new URL(context.req.url);
+        requireKnownQuery(url, ["of", "folderId", "flowId", "limit"]);
+        const of = url.searchParams.get("of");
+        const input = RelationGraphInput.parse({
+            scope: of === "flow"
+                ? { of: "flow", flowId: url.searchParams.get("flowId") ?? "" }
+                : { of: "folder", folderId: url.searchParams.get("folderId") || null },
+            limit: url.searchParams.has("limit") ? Number(url.searchParams.get("limit")) : undefined,
+        });
+        return context.json(await deps.flows.relationGraph(asFlowActor(auth), input));
     });
+    // A path variable is a door like any other, so it is parsed rather than trusted: `GetFlowInput`
+    // is the same schema the body-carrying routes and the MCP tools use for this identifier.
     app.get("/flows/:flowId", async (context) => {
         const auth = requireCapability(context, "flows", "read");
-        return context.json(await deps.flows.get(asFlowActor(auth), context.req.param("flowId")));
-    });
-    app.get("/flows/:flowId/grants", async (context) => {
-        const auth = requireCapability(context, "flows", "share");
-        return context.json(await deps.flows.listGrants(asFlowActor(auth), context.req.param("flowId")));
+        const input = GetFlowInput.parse({ flowId: context.req.param("flowId") });
+        return context.json(await deps.flows.get(asFlowActor(auth), input.flowId));
     });
-    app.post("/flows/:flowId/grants", async (context) => {
-        const auth = requireCapability(context, "flows", "share");
-        const input = ShareFlowInput.parse(await context.req.json().catch(() => null));
-        if (input.resourceId !== context.req.param("flowId")) {
-            throw new IntelError(400, "flow_id_mismatch", "Path and body flow IDs differ");
-        }
-        return context.json(await deps.flows.share(asFlowActor(auth), input), 201);
+    // What this flow calls, read out of its graph. The tree lists where a flow is filed; this lists
+    // what it runs, and a shared subflow answers both questions at once (ADR-0004 §3).
+    app.get("/flows/:flowId/calls", async (context) => {
+        const auth = requireCapability(context, "flows", "read");
+        const input = GetFlowInput.parse({ flowId: context.req.param("flowId") });
+        return context.json(await deps.flows.listCalls(asFlowActor(auth), input.flowId));
     });
-    app.post("/flows/:flowId/grants/:grantId/revoke", async (context) => {
-        const auth = requireCapability(context, "flows", "share");
-        const input = RevokeFlowGrantInput.parse(await context.req.json().catch(() => null));
-        if (input.resourceId !== context.req.param("flowId") ||
-            input.grantId !== context.req.param("grantId")) {
-            throw new IntelError(400, "grant_id_mismatch", "Path and body grant IDs differ");
-        }
-        return context.json(await deps.flows.revokeGrant(asFlowActor(auth), input));
+    // What this flow needs: the documents and tools its graph names. `flows/read` and nothing more —
+    // it describes a flow the caller may already open, and names only what they may already see.
+    app.get("/flows/:flowId/requirements", async (context) => {
+        const auth = requireCapability(context, "flows", "read");
+        const input = GetFlowInput.parse({ flowId: context.req.param("flowId") });
+        return context.json(await deps.flows.listRequirements(asFlowActor(auth), input.flowId));
     });
+    // A flow has no grant route of its own. It is shared through the folder it is filed in, under
+    // /knowledge/:nodeId/grants — one place answers the question for the documents and the flows in
+    // that folder alike (ADR-0004 §2).
     app.post("/flows", async (context) => {
         const auth = requireCapability(context, "flows", "create");
         const input = CreateFlowInput.parse(await context.req.json().catch(() => null));
         return context.json(await deps.flows.create(asFlowActor(auth), input), 201);
     });
+    app.patch("/flows/:flowId", async (context) => {
+        const auth = requireCapability(context, "flows", "write");
+        const input = UpdateFlowInput.parse(await context.req.json().catch(() => null));
+        if (input.flowId !== context.req.param("flowId")) {
+            throw new IntelError(400, "flow_id_mismatch", "Path and body flow IDs differ");
+        }
+        return context.json(await deps.flows.update(asFlowActor(auth), input));
+    });
     app.post("/flows/:flowId/versions", async (context) => {
         const auth = requireCapability(context, "flows", "write");
         const input = SaveFlowVersionInput.parse(await context.req.json().catch(() => null));
@@ -240,6 +314,16 @@ export function createHttp(deps) {
         }
         return context.json(await deps.flows.save(asFlowActor(auth), input), 201);
     });
+    // What publishing would freeze, before it is published (ADR-0004 §5). A GET because it reads and
+    // changes nothing; the `publish` capability because it answers a question only a publisher has.
+    app.get("/flows/:flowId/versions/:versionId/publish-preview", async (context) => {
+        const auth = requireCapability(context, "flows", "publish");
+        const input = PreviewFlowPublishInput.parse({
+            flowId: context.req.param("flowId"),
+            versionId: context.req.param("versionId"),
+        });
+        return context.json(await deps.flows.previewPublish(asFlowActor(auth), input));
+    });
     app.post("/flows/:flowId/publish", async (context) => {
         const auth = requireCapability(context, "flows", "publish");
         const input = PublishFlowInput.parse(await context.req.json().catch(() => null));
@@ -256,9 +340,33 @@ export function createHttp(deps) {
         }
         return context.json(await deps.flows.start(asFlowActor(auth), input), 201);
     });
+    // What this flow has done (#35). A GET beside `POST /flows/:flowId/runs`: the same collection,
+    // read instead of appended to. `flows/read` is the capability, and which of the runs actually
+    // appear is the resource rule the service applies per row.
+    app.get("/flows/:flowId/runs", async (context) => {
+        const auth = requireCapability(context, "flows", "read");
+        const url = new URL(context.req.url);
+        requireKnownQuery(url, ["failedOnly", "limit", "cursor"]);
+        const input = ListFlowRunsInput.parse({
+            flowId: context.req.param("flowId"),
+            // Present means "only the failed ones". A query string carries no booleans, so the parameter's
+            // presence is the flag rather than a string that would have to be spelled exactly right.
+            ...(url.searchParams.has("failedOnly") ? { failedOnly: true } : {}),
+            ...(url.searchParams.has("limit") ? { limit: Number(url.searchParams.get("limit")) } : {}),
+            ...(url.searchParams.has("cursor") ? { cursor: url.searchParams.get("cursor") } : {}),
+        });
+        return context.json(await deps.flows.listRuns(asFlowActor(auth), input));
+    });
     app.get("/flow-runs/:runId", async (context) => {
         const auth = requireCapability(context, "flows", "read");
-        return context.json(await deps.flows.getRun(asFlowActor(auth), context.req.param("runId")));
+        const input = GetFlowRunInput.parse({ runId: context.req.param("runId") });
+        return context.json(await deps.flows.getRun(asFlowActor(auth), input.runId));
+    });
+    // The drill-down behind the list: which step of this run ended it, and what it said.
+    app.get("/flow-runs/:runId/steps", async (context) => {
+        const auth = requireCapability(context, "flows", "read");
+        const input = GetFlowRunInput.parse({ runId: context.req.param("runId") });
+        return context.json(await deps.flows.listRunSteps(asFlowActor(auth), input.runId));
     });
     app.post("/flow-runs/:runId/complete", async (context) => {
         const auth = requireCapability(context, "flows", "run");

package/dist/indexing/indexing.js

@@ -13,15 +13,26 @@ function indexText(mediaType, content) {
         throw new PermanentIndexingError(`Knowledge version content is not a valid BlockNote document: ${error instanceof Error ? error.message : "unknown parse failure"}`);
     }
 }
+async function readCanonical(deps, target) {
+    if (target.kind === "attachment") {
+        const key = target.contentKeys[0];
+        return key === undefined ? null : await deps.content.getBytes(key);
+    }
+    const segments = await Promise.all(target.contentKeys.map(async (key) => await deps.content.get(key)));
+    if (segments.length === 0 || segments.some((segment) => segment === null))
+        return null;
+    return segments.join("");
+}
 export function createIndexing(deps) {
     return {
         async index(versionId) {
             const target = await deps.repository.getTarget(versionId);
             if (!target)
                 return;
-            const canonical = target.kind === "attachment"
-                ? await deps.content.getBytes(target.contentKey)
-                : await deps.content.get(target.contentKey);
+            // An attachment is one object of bytes; text kinds may be several, because a table's content
+            // is the join of its versions (#40). A missing segment fails the whole pass rather than
+            // indexing a table with a hole in it.
+            const canonical = await readCanonical(deps, target);
             if (canonical === null) {
                 await deps.repository.markError(versionId, "content_missing", deps.now().toISOString());
                 throw new Error("Knowledge version content is missing");

package/dist/knowledge/document-links/document-links.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The documents one saved document links to, read out of its own content (#41).
+ *
+ * ⚠️ The IDs and nothing else. A document link stores no title and no path, so there is nothing in
+ * here that could go stale when the target is renamed or moved — and nothing that could carry a
+ * name out of a part of the tree the reader may not see.
+ *
+ * ⚠️ Deliberately tolerant of shapes it does not know. This walks stored content, which an older or
+ * newer editor wrote; a strict parse would turn "I do not recognise this block" into "this document
+ * cannot be saved". What it does not recognise contributes no link, which is the safe half.
+ *
+ * Content that is not a BlockNote document has no links at all: an attachment, a CSV table or plain
+ * markdown carries no inline element to read.
+ */
+export declare function documentLinkTargets(mediaType: string, content: string): string[];

package/dist/knowledge/document-links/document-links.js

@@ -0,0 +1,52 @@
+import { BlockNoteDocument, BlockNoteMediaType, DocumentLinkInlineType, } from "@anchrd/intel-contract";
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+function collect(value, found) {
+    if (Array.isArray(value)) {
+        for (const entry of value)
+            collect(entry, found);
+        return;
+    }
+    if (!isRecord(value))
+        return;
+    if (value.type === DocumentLinkInlineType) {
+        const props = value.props;
+        const nodeId = isRecord(props) ? props.nodeId : undefined;
+        if (typeof nodeId === "string" && nodeId.length > 0)
+            found.add(nodeId);
+    }
+    collect(value.content, found);
+    collect(value.children, found);
+}
+/**
+ * The documents one saved document links to, read out of its own content (#41).
+ *
+ * ⚠️ The IDs and nothing else. A document link stores no title and no path, so there is nothing in
+ * here that could go stale when the target is renamed or moved — and nothing that could carry a
+ * name out of a part of the tree the reader may not see.
+ *
+ * ⚠️ Deliberately tolerant of shapes it does not know. This walks stored content, which an older or
+ * newer editor wrote; a strict parse would turn "I do not recognise this block" into "this document
+ * cannot be saved". What it does not recognise contributes no link, which is the safe half.
+ *
+ * Content that is not a BlockNote document has no links at all: an attachment, a CSV table or plain
+ * markdown carries no inline element to read.
+ */
+export function documentLinkTargets(mediaType, content) {
+    if (mediaType !== BlockNoteMediaType)
+        return [];
+    let parsed;
+    try {
+        parsed = JSON.parse(content);
+    }
+    catch {
+        return [];
+    }
+    const document = BlockNoteDocument.safeParse(parsed);
+    if (!document.success)
+        return [];
+    const found = new Set();
+    collect(document.data.blocks, found);
+    return [...found];
+}