@anchrd/intel 0.59.0

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

@@ -0,0 +1,339 @@
+import type { ArchiveFlowInput, CreateFlowInput, Flow, FlowDocument, FlowGraph, FlowPublishPreview, FlowRequirements, FlowValidation, FlowVersion, FlowVersionList, FlowVersionSummary, GetFlowVersionInput, ListFlowsInput, PreviewFlowPublishInput, PublishFlowInput, RelationGraph, RelationGraphInput, SaveFlowVersionInput, UnpublishFlowInput, UpdateFlowInput } from "../contract/flow.js";
+import type { CancelFlowRunInput, CompleteFlowRunStepInput, FlowRun, FlowRunHistory, FlowRunList, FlowRunStep, ListFlowRunsInput, StartFlowRunInput } from "../contract/flow-run.js";
+import type { Node } from "../contract/node.js";
+import type { ResourceAccessList, ResourceGrant, ResourceGrantList, ResourceVerb, RevokeFlowGrantInput, RevokeGrantResult, ShareFlowInput, ShareResult } from "../contract/share.js";
+import type { PromptNameHolder } from "../prompts/prompts.types.js";
+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 | null;
+    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;
+    isAdmin?: boolean;
+}
+export type FlowVerb = ResourceVerb;
+export type FlowOperation = "flows.create" | "flows.update" | "flows.archive" | "flows.save" | "flows.publish" | "flows.run" | "flows.complete" | "flows.cancel" | "flows.unpublish" | "flows.share" | "flows.revoke";
+export interface BoundedLevel<T> {
+    items: T[];
+    total: number;
+}
+export interface FlowRepository {
+    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>;
+    can(actor: FlowActor, flowId: string, verb: FlowVerb): Promise<boolean>;
+    listFlowGrants(flowId: string): Promise<ResourceGrant[]>;
+    listEffectiveFlowAccess(flowId: string): Promise<{
+        ownerIds: string[];
+        items: ResourceGrant[];
+    }>;
+    setFlowGrant(input: {
+        grant: ResourceGrant;
+        flowId: string;
+        actorId: string;
+        idempotencyKey: string;
+        auditId: string;
+    }): Promise<ResourceGrant>;
+    revokeFlowGrant(input: {
+        flowId: string;
+        grantId: string;
+        actorId: string;
+        idempotencyKey: string;
+        auditId: string;
+        occurredAt: string;
+    }): Promise<boolean>;
+    findIdempotentFlowRevocation(actorId: string, idempotencyKey: string): Promise<boolean | null>;
+    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;
+    }>;
+    nodeReferences(actor: FlowPrincipal, folderId: string): Promise<string[]>;
+    /**
+     * Which of these ids still have a row in the tree at all — archived or not, for anybody (#509).
+     *
+     * ⚠️ It takes NO actor, and that is the honest shape rather than an oversight: the answer does
+     * not depend on who is asking, so an `actor` parameter would suggest a narrowing that is not
+     * there. Its one caller has already asked `visibleNodes` and only reaches this for the ids that
+     * came back empty, so what it adds is a single bit about ids the caller sent us out of a graph
+     * they may already read.
+     *
+     * ⚠️ An ARCHIVED node counts as existing. Archiving is reversible — the row is still there and a
+     * restore brings the reference back — so calling it invalid would tell an author to replace a
+     * step that is about to work again. Only a purge takes the row (`DELETE FROM nodes`, #457), and
+     * only that is what "there is nothing here any more" means.
+     */
+    existingNodes(nodeIds: string[]): Promise<string[]>;
+    publishedCallees(flowId: string): Promise<{
+        title: string;
+        calleeIds: string[];
+    } | null>;
+    findIdempotent(actorId: string, operation: FlowOperation, key: string): Promise<string | 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>;
+    archiveFlow(input: {
+        flowId: string;
+        baseUpdatedAt: string;
+        archivedAt: string | null;
+        updatedAt: string;
+        actorId: string;
+        idempotencyKey: string;
+        auditId: string;
+    }): Promise<"conflict" | Flow>;
+    flowsUsingNode(actor: FlowActor, nodeId: string): Promise<{
+        visible: string[];
+        hidden: number;
+    }>;
+    flowCallers(actor: FlowActor, flowId: string): Promise<{
+        visible: string[];
+        hidden: number;
+    }>;
+    hasEntangledRuns(flowId: string): Promise<boolean>;
+    hasUnfinishedRuns(flowId: string): Promise<boolean>;
+    purgeFlow(input: {
+        flowId: string;
+        actorId: string;
+        auditId: string;
+        occurredAt: string;
+    }): Promise<"missing" | {
+        purged: true;
+    }>;
+    getVersion(versionId: string): Promise<FlowVersion | null>;
+    listVersions(flowId: string): Promise<Omit<FlowVersionSummary, "published">[]>;
+    getVersions(versionIds: string[]): Promise<FlowVersion[]>;
+    insertVersion(input: {
+        version: FlowVersion;
+        baseVersionId: string | null;
+        actorId: string;
+        idempotencyKey: string;
+        auditId: string;
+    }): Promise<"saved" | "conflict">;
+    publish(input: {
+        flowId: string;
+        versionId: string;
+        actorId: string;
+        idempotencyKey: string;
+        auditId: string;
+        occurredAt: string;
+        /**
+         * The slash command this flow is offered under (#775). ⚠️ Three states, and `undefined` is the
+         * one that does nothing: publishing a second version of an already-offered flow must not
+         * withdraw its command, so a caller who says nothing about prompts changes nothing about them.
+         * `null` gives the name up, a string takes one.
+         */
+        promptName?: string | null;
+    }): Promise<boolean | "prompt_name_taken">;
+    /**
+     * Who holds a slash command name, for the sentence a refused publish gets. `title` is `null` when
+     * the holder exists but this actor may not see it — the same one implementation the node
+     * repository answers with (`db-prompts.ts`).
+     */
+    promptNameHolder(actor: FlowActor, name: string): Promise<PromptNameHolder | null>;
+    unpublish(input: {
+        flowId: string;
+        versionId: string;
+        actorId: string;
+        idempotencyKey: string;
+        auditId: string;
+        occurredAt: string;
+    }): Promise<boolean>;
+    insertRun(input: {
+        run: FlowRun;
+        actorId: string;
+        idempotencyKey: string;
+        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[]>;
+    /**
+     * End a run and every non-terminal run below it in one write (#145). The recursion follows
+     * `parent_run_id`, so cancelling a caller cannot leave a called run working for a result nobody
+     * will ever read. No step row is written for any of them: cancelling is not a step outcome, and
+     * inventing a failed step is exactly what this operation exists to replace.
+     *
+     * `"conflict"` means the run was already terminal when the write arrived — the caller's status
+     * check raced another writer — and nothing was changed. `cancelled` names every run this write
+     * ended, so the service can wake each of their durable waits.
+     */
+    cancelRun(input: {
+        runId: string;
+        flowId: string;
+        actorId: string;
+        occurredAt: string;
+        idempotencyKey: string;
+        auditId: string;
+    }): Promise<"conflict" | {
+        cancelled: string[];
+    }>;
+    advanceRun(input: {
+        run: FlowRun;
+        expectedNodeId: string;
+        actorId: string;
+        stepId: string;
+        outcome: "completed" | "failed";
+        branch: string | null;
+        output: unknown;
+        error: string | null;
+        idempotencyKey: string;
+        auditId: string;
+    }): Promise<"advanced" | "conflict">;
+}
+export interface FlowRuntime {
+    start(runId: string): Promise<void>;
+    signal(runId: string): Promise<void>;
+}
+export interface FlowDeps {
+    repository: FlowRepository;
+    runtime: FlowRuntime;
+    id(): string;
+    now(): Date;
+    folderAccess(actor: FlowActor, folderId: string): Promise<FolderAccess>;
+    parentArchivedAt(folderId: string): Promise<{
+        archivedAt: string | null;
+        kind: string;
+    } | null>;
+    /**
+     * The children of one folder of the shared tree as this actor may see them, without their bodies.
+     * `null` is the root. The node service 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.
+     */
+    nodeChildren(actor: FlowActor, folderId: string | null, limit: number): Promise<BoundedLevel<Node>>;
+    /**
+     * 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 tree link 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.
+     *
+     * ⚠️ `existingNodes` on the repository is the ONE thing asked beside it, and it is the exception
+     * that shows the rule rather than a hole in it: it runs only on ids this door already refused, it
+     * takes no actor, and it can only ever make the answer HARSHER — "this names nothing" instead of
+     * "you cannot see it". Nothing about a node it does hold reaches the caller, so no drawing and no
+     * message becomes kinder. Adding a third would need the same three properties (#492, #509).
+     */
+    visibleNodes(actor: FlowActor, nodeId: string): Promise<Node | null>;
+    /**
+     * Whether this actor may manage sharing of a NODE (#825) — straight to the same predicate
+     * `node_effective_access_list` refuses without (`nodes.ts:1537`). The relation graph asks it once
+     * per node already known to be visible, before drawing a single access edge off it.
+     *
+     * ⚠️ Optional on purpose. It bridges to the node service exactly like `visibleNodes` above, but
+     * adding a required field here would touch every one of the several dozen fixtures across this
+     * package that construct a `FlowDeps` for a test that never exercises the relation graph's outer
+     * ring. The real composition always provides it; where a test omits it, the graph simply carries
+     * no users and no access edges — the same "cannot draw it" shape `omitted` already uses.
+     */
+    nodeShareable?(actor: FlowActor, nodeId: string): Promise<boolean>;
+    nodeEffectiveAccess?(nodeId: string): Promise<{
+        ownerIds: string[];
+        items: ResourceGrant[];
+    }>;
+    toolSurfaceFingerprint(actor: FlowActor, server: string, allow: string[] | null): Promise<string | null>;
+    unavailableServers(actor: FlowActor, servers: string[]): Promise<string[]>;
+}
+export type FolderAccess = "ok" | "missing" | "not-a-folder" | "forbidden";
+export interface FlowService {
+    list(actor: FlowActor, input?: ListFlowsInput): Promise<{
+        items: Flow[];
+        withCalls: string[];
+    }>;
+    get(actor: FlowActor, flowId: string): Promise<FlowDocument>;
+    listVersions(actor: FlowActor, flowId: string): Promise<FlowVersionList>;
+    getVersion(actor: FlowActor, input: GetFlowVersionInput): Promise<FlowVersion>;
+    listCalls(actor: FlowActor, flowId: string): Promise<{
+        items: Flow[];
+        withCalls: string[];
+    }>;
+    validate(actor: FlowActor, flowId: string): Promise<FlowValidation>;
+    relationGraph(actor: FlowActor, input: RelationGraphInput): Promise<RelationGraph>;
+    listRequirements(actor: FlowActor, flowId: string): Promise<FlowRequirements>;
+    listGrants(actor: FlowActor, flowId: string): Promise<ResourceGrantList>;
+    listEffectiveAccess(actor: FlowActor, flowId: string): Promise<ResourceAccessList>;
+    share(actor: FlowActor, input: ShareFlowInput): Promise<ShareResult>;
+    revokeGrant(actor: FlowActor, input: RevokeFlowGrantInput): Promise<RevokeGrantResult>;
+    create(actor: FlowActor, input: CreateFlowInput): Promise<Flow>;
+    update(actor: FlowActor, input: UpdateFlowInput): Promise<Flow>;
+    archive(actor: FlowActor, input: ArchiveFlowInput): Promise<Flow>;
+    purge(actor: FlowActor, input: {
+        flowId: string;
+    }): Promise<{
+        purged: true;
+        title: string;
+    }>;
+    save(actor: FlowActor, input: SaveFlowVersionInput): Promise<FlowDocument>;
+    previewPublish(actor: FlowActor, input: PreviewFlowPublishInput): Promise<FlowPublishPreview>;
+    publish(actor: FlowActor, input: PublishFlowInput): Promise<Flow>;
+    unpublish(actor: FlowActor, input: UnpublishFlowInput): 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>;
+    cancelRun(actor: FlowActor, input: CancelFlowRunInput): Promise<FlowRunStep>;
+}
+export interface CompiledFlow {
+    graph: FlowGraph;
+    triggerId: string;
+}
+export interface RunProblem {
+    status: number;
+    code: string;
+    detail: string;
+}

package/dist/flows/flows.types.js

@@ -0,0 +1 @@
+export {};

package/dist/http/http.d.ts

@@ -0,0 +1,9 @@
+import type { Authorized } from "@anchrd/gate-sdk";
+import { Hono } from "hono";
+import type { HttpDeps } from "./http.types.js";
+export declare function createHttp(deps: HttpDeps): Hono<{
+    Variables: {
+        authorization: Authorized;
+        token: string;
+    };
+}, import("hono/types").BlankSchema, "/">;