@anchrd/intel-api 0.6.3 → 0.6.4

package/dist/adapters/db/db-flows.js

@@ -122,15 +122,15 @@ export function createFlowRepository(deps) {
      * same reason `COUNT(*) OVER ()` is a count of those rows alone — the number the graph reports
      * about its own size would otherwise disclose that something else is there.
      */
-    const visibleFlows = (scopeClause, bounded) => `${subtreeCte}
+    const visibleFlows = (scopeClause, bounded, includeArchived = false) => `${subtreeCte}
     SELECT ${flowColumns}${bounded ? ", COUNT(*) OVER () AS total" : ""} FROM flows flow
-    WHERE ${flowInSubtree} AND flow.archived_at IS NULL ${scopeClause}
+    WHERE ${flowInSubtree} ${includeArchived ? "" : "AND flow.archived_at IS NULL"} ${scopeClause}
     ORDER BY lower(flow.title), flow.id${bounded ? " LIMIT ?" : ""}`;
     return {
         async listVisible(actor, input = {}) {
             const scope = scopeOf(input.parentId);
             const result = await deps.db
-                .prepare(visibleFlows(scope.clause, false))
+                .prepare(visibleFlows(scope.clause, false, input.includeArchived === true))
                 .bind(...readableBindings(actor), ...flowInSubtreeBindings(actor), ...scope.bindings)
                 .all();
             return (result.results ?? []).map(mapFlow);
@@ -388,6 +388,55 @@ export function createFlowRepository(deps) {
                 .first();
             return row ? mapFlow(row) : "conflict";
         },
+        // Archiving and restoring are one statement, told apart only by whether `archived_at` is a
+        // timestamp or null. Like `updateFlow` it writes the flow row alone: an archived flow keeps its
+        // versions and its published version, because coming back out of the archive has to return the
+        // flow that went in.
+        //
+        // ⚠️ The idempotency row is written only if the UPDATE actually matched — same guard as
+        // `knowledge.archive` — so a stale `baseUpdatedAt` leaves no key behind that would make the
+        // retry of a *lost* write look like a replay of a successful one.
+        async archiveFlow(input) {
+            try {
+                await deps.db.batch([
+                    deps.db
+                        .prepare(`UPDATE flows SET archived_at = ?, updated_at = ?
+              WHERE id = ? AND updated_at = ?`)
+                        .bind(input.archivedAt, input.updatedAt, input.flowId, input.baseUpdatedAt),
+                    deps.db
+                        .prepare(`INSERT INTO idempotency_keys (
+              actor_id, operation, idempotency_key, resource_id, created_at
+            ) SELECT ?, 'flows.archive', ?, ?, ?
+            WHERE EXISTS (
+              SELECT 1 FROM flows WHERE id = ? AND archived_at IS ? AND updated_at = ?
+            )`)
+                        .bind(input.actorId, input.idempotencyKey, input.flowId, input.updatedAt, input.flowId, input.archivedAt, input.updatedAt),
+                    deps.db
+                        .prepare(`INSERT INTO audit_events (
+              id, actor_id, action, resource_type, resource_id, metadata_json, occurred_at
+            ) SELECT ?, ?, 'flows.archive', 'flow', ?, ?, ?
+            WHERE EXISTS (
+              SELECT 1 FROM idempotency_keys
+              WHERE actor_id = ? AND operation = 'flows.archive'
+                AND idempotency_key = ? AND resource_id = ?
+            )`)
+                        .bind(input.auditId, input.actorId, input.flowId, JSON.stringify({ archived: input.archivedAt !== null }), input.updatedAt, input.actorId, input.idempotencyKey, input.flowId),
+                ]);
+            }
+            catch (error) {
+                if (!(await this.findIdempotent(input.actorId, "flows.archive", input.idempotencyKey))) {
+                    throw error;
+                }
+            }
+            const replayed = await this.findIdempotent(input.actorId, "flows.archive", input.idempotencyKey);
+            if (!replayed)
+                return "conflict";
+            const row = await deps.db
+                .prepare(`SELECT ${flowColumns} FROM flows WHERE id = ?`)
+                .bind(replayed)
+                .first();
+            return row ? mapFlow(row) : "conflict";
+        },
         // Versions are immutable, so a set of them is a single read by definition: the trail of a nested
         // run needs one per level and the relation graph one per flow it draws, and both used to ask
         // level by level (#30). Missing IDs are simply absent from the answer.

package/dist/flows/flows.js

@@ -1053,6 +1053,56 @@ export function createFlows(deps) {
             }
             return updated;
         },
+        /**
+         * Archive a flow, or take it back out again.
+         *
+         * ⚠️ The one place that resolves the flow through `getVisible` instead of `requireFlow`. Every
+         * other entry point treats an archived flow as absent — that is the whole point of archiving —
+         * but the call that restores one has to be able to find it, and `requireFlow` answers 404 for
+         * exactly the rows this call exists for. The visibility predicate is the same one; only the
+         * `archivedAt` refusal is left out.
+         *
+         * `write` and nothing more, asked before the row is touched: archiving is organization, the same
+         * grant that renames and moves (ADR-0004). It appends no version and withdraws no publication.
+         *
+         * ⚠️ It does NOT leave runs in flight alone, however much the word "archive" suggests it would.
+         * `completeStep` writes before it shapes its answer: the step is recorded, and `step()` then
+         * resolves the flow and throws 404 for the archived one. The caller is told the step failed
+         * while storage has it done, and a retry replays into the same 404. Restoring the flow is what
+         * makes the run readable again. That belongs to the run machine and has its own ticket
+         * (issue 112) — archiving is only the easiest way to walk into it.
+         */
+        async archive(actor, input) {
+            const current = await deps.repository.getVisible(actor, input.flowId);
+            if (!current)
+                throw new IntelError(404, "flow_not_found", "Flow was not found");
+            if (!(await deps.repository.can(actor, input.flowId, "write"))) {
+                throw new IntelError(403, "flow_edit_forbidden", "Flow cannot be edited");
+            }
+            const replayed = await deps.repository.findIdempotent(actor.id, "flows.archive", input.idempotencyKey);
+            // Read back the way this call reads anything, or replaying an archive would 404 on the row it
+            // just archived.
+            if (replayed) {
+                const flow = await deps.repository.getVisible(actor, replayed);
+                if (!flow)
+                    throw new IntelError(404, "flow_not_found", "Flow was not found");
+                return flow;
+            }
+            const updatedAt = deps.now().toISOString();
+            const updated = await deps.repository.archiveFlow({
+                flowId: current.id,
+                baseUpdatedAt: input.baseUpdatedAt,
+                archivedAt: input.archived ? updatedAt : null,
+                updatedAt,
+                actorId: actor.id,
+                idempotencyKey: input.idempotencyKey,
+                auditId: deps.id(),
+            });
+            if (updated === "conflict") {
+                throw new IntelError(409, "flow_update_conflict", "Flow was changed by another editor");
+            }
+            return updated;
+        },
         async save(actor, input) {
             const replayed = await deps.repository.findIdempotent(actor.id, "flows.save", input.idempotencyKey);
             if (replayed) {

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

@@ -1,4 +1,4 @@
-import type { CompleteFlowRunStepInput, CreateFlowInput, Flow, FlowDocument, FlowGraph, FlowPublishPreview, FlowRequirements, FlowRun, FlowRunHistory, FlowRunList, FlowRunStep, FlowValidation, FlowVersion, KnowledgeNode, ListFlowRunsInput, ListFlowsInput, PreviewFlowPublishInput, PublishFlowInput, RelationGraph, RelationGraphInput, ResourceVerb, SaveFlowVersionInput, StartFlowRunInput, UpdateFlowInput } from "@anchrd/intel-contract";
+import type { ArchiveFlowInput, CompleteFlowRunStepInput, CreateFlowInput, Flow, FlowDocument, FlowGraph, FlowPublishPreview, FlowRequirements, FlowRun, FlowRunHistory, FlowRunList, FlowRunStep, FlowValidation, 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 {
@@ -40,7 +40,7 @@ export interface FlowActor {
     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 type FlowOperation = "flows.create" | "flows.update" | "flows.archive" | "flows.save" | "flows.publish" | "flows.run" | "flows.complete";
 export interface BoundedLevel<T> {
     items: T[];
     total: number;
@@ -76,6 +76,15 @@ export interface FlowRepository {
         idempotencyKey: string;
         auditId: string;
     }): Promise<"conflict" | Flow>;
+    archiveFlow(input: {
+        flowId: string;
+        baseUpdatedAt: string;
+        archivedAt: string | null;
+        updatedAt: string;
+        actorId: string;
+        idempotencyKey: string;
+        auditId: string;
+    }): Promise<"conflict" | Flow>;
     getVersion(versionId: string): Promise<FlowVersion | null>;
     getVersions(versionIds: string[]): Promise<FlowVersion[]>;
     insertVersion(input: {
@@ -169,6 +178,7 @@ export interface FlowService {
     listRequirements(actor: FlowActor, flowId: string): Promise<FlowRequirements>;
     create(actor: FlowActor, input: CreateFlowInput): Promise<Flow>;
     update(actor: FlowActor, input: UpdateFlowInput): Promise<Flow>;
+    archive(actor: FlowActor, input: ArchiveFlowInput): Promise<Flow>;
     save(actor: FlowActor, input: SaveFlowVersionInput): Promise<FlowDocument>;
     previewPublish(actor: FlowActor, input: PreviewFlowPublishInput): Promise<FlowPublishPreview>;
     publish(actor: FlowActor, input: PublishFlowInput): Promise<Flow>;

package/dist/http/http.js

@@ -1,4 +1,4 @@
-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 { AppendKnowledgeTableRowsInput, ArchiveFlowInput, 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, permits, } from "../shared/gate-authorization/gate-authorization.js";
@@ -250,11 +250,16 @@ export function createHttp(deps) {
     app.get("/flows", async (context) => {
         const auth = requireCapability(context, "flows", "read");
         const url = new URL(context.req.url);
-        requireKnownQuery(url, ["parentId"]);
+        requireKnownQuery(url, ["parentId", "includeArchived"]);
         // 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 } : {});
+        // Same rule for the archive: absent means "without it". Spelling the default out would put a
+        // field into every call that asks nothing about the archive.
+        const input = ListFlowsInput.parse({
+            ...(url.searchParams.has("parentId") ? { parentId: parentId === "" ? null : parentId } : {}),
+            ...(url.searchParams.get("includeArchived") === "true" ? { includeArchived: true } : {}),
+        });
         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
@@ -318,6 +323,16 @@ export function createHttp(deps) {
         }
         return context.json(await deps.flows.update(asFlowActor(auth), input));
     });
+    // `flows/write`, the same capability renaming and moving need: archiving is organization, not a
+    // change to what the flow does.
+    app.post("/flows/:flowId/archive", async (context) => {
+        const auth = requireCapability(context, "flows", "write");
+        const input = ArchiveFlowInput.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.archive(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));

package/dist/mcp/mcp.js

@@ -1,4 +1,4 @@
-import { AppendKnowledgeTableRowsInput, ArchiveKnowledgeNodeInput, CompleteFlowRunStepInput, CreateFlowInput, CreateKnowledgeNodeInput, DefineKnowledgeTableInput, ExecuteToolInput, GetFlowInput, GetFlowRunInput, GetKnowledgeNodeInput, GetKnowledgeTableInput, KnowledgeGraphInput, ListFlowRunsInput, ListFlowsInput, ListKnowledgeGrantsInput, ListKnowledgeNodesInput, PreviewFlowPublishInput, PublishFlowInput, RelationGraphInput, ResolveKnowledgeLinksInput, RevokeKnowledgeGrantInput, SaveFlowVersionInput, SaveKnowledgeAttachmentInput, SaveKnowledgeVersionInput, SearchKnowledgeInput, ShareKnowledgeInput, StartFlowRunInput, TestToolInput, UpdateFlowInput, UpdateKnowledgeNodeInput, } from "@anchrd/intel-contract";
+import { AppendKnowledgeTableRowsInput, ArchiveFlowInput, ArchiveKnowledgeNodeInput, CompleteFlowRunStepInput, CreateFlowInput, CreateKnowledgeNodeInput, DefineKnowledgeTableInput, ExecuteToolInput, GetFlowInput, GetFlowRunInput, GetKnowledgeNodeInput, GetKnowledgeTableInput, KnowledgeGraphInput, ListFlowRunsInput, ListFlowsInput, ListKnowledgeGrantsInput, ListKnowledgeNodesInput, PreviewFlowPublishInput, PublishFlowInput, RelationGraphInput, ResolveKnowledgeLinksInput, RevokeKnowledgeGrantInput, SaveFlowVersionInput, SaveKnowledgeAttachmentInput, SaveKnowledgeVersionInput, SearchKnowledgeInput, ShareKnowledgeInput, StartFlowRunInput, TestToolInput, UpdateFlowInput, UpdateKnowledgeNodeInput, } from "@anchrd/intel-contract";
 import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
 import { z } from "zod";
@@ -473,6 +473,20 @@ export async function handleMcp(request, deps) {
                 openWorldHint: false,
             },
         }, async (input) => text(await deps.flows.update(flowActor, input)));
+        server.registerTool("flow_archive", {
+            title: "Archive flow",
+            description: "Archive or restore one flow using optimistic concurrency. An archived flow keeps its versions but can no longer be opened, started, or called by another flow.",
+            inputSchema: ArchiveFlowInput,
+            annotations: {
+                title: "Archive flow",
+                readOnlyHint: false,
+                // What it takes away is reach, not content: nothing is deleted and `archived: false` puts
+                // it back. Destructive all the same, because a flow another flow calls stops resolving.
+                destructiveHint: true,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+        }, async (input) => text(await deps.flows.archive(flowActor, input)));
         server.registerTool("flow_save", {
             title: "Save flow",
             description: "Append a validated immutable flow graph version with optimistic concurrency.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anchrd/intel-api",
-  "version": "0.6.3",
+  "version": "0.6.4",
   "type": "module",
   "license": "UNLICENSED",
   "repository": {