@punica/editor 1.0.5 → 1.0.7

package/types/punica.module.flow.d.ts

@@ -0,0 +1,490 @@
+/// <reference path="./punica.module.capability.d.ts" />
+/// <reference path="./punica.module.test.d.ts" />
+
+declare module 'punica' {
+  // eslint-disable-next-line @typescript-eslint/no-namespace
+  export namespace flow {
+    /**
+     * Minimal JSON types (self-contained to keep this experimental surface decoupled).
+     */
+    export type JSONPrimitive = string | number | boolean | null;
+    export type JSONValue =
+      | JSONPrimitive
+      | JSONValue[]
+      | { [key: string]: JSONValue };
+    export interface JSONObject {
+      [key: string]: JSONValue;
+    }
+
+    /**
+     * View metadata (purely UI state).
+     */
+    export interface ViewMetadata {
+      viewport?: { x: number; y: number; zoom: number };
+      nodes?: {
+        [id: string]: {
+          x?: number;
+          y?: number;
+          collapsed?: boolean;
+          [key: string]: JSONValue | undefined;
+        };
+      };
+      [key: string]: unknown;
+    }
+
+    /**
+     * Execution policy primitives.
+     */
+    export type CancellationMode = 'best-effort' | 'hard';
+
+    export interface RunBudget {
+      maxInFlight?: number;
+      maxQueueSize?: number;
+      totalTimeoutMs?: number;
+      cancellationMode?: CancellationMode;
+      /**
+       * Opt-in fail-fast semantic for parallel execution (D6). When
+       * `true`, the executor cancels in-flight siblings on the first
+       * node failure within a batch. Default is continue-and-collect
+       * so existing flows are not broken by the upgrade.
+       */
+      failFast?: boolean;
+      /**
+       * Persistence size budget per run (persistence redaction & budget, F27). Substrate
+       * tracks accumulated artifact bytes; writes that would exceed
+       * `maxBytes` produce a `redacted: { reason: 'budget' }` sentinel
+       * artifact instead of a plaintext payload, so audit traces
+       * remain coherent without unbounded disk growth.
+       */
+      artifactBudget?: ArtifactSizeBudget;
+    }
+
+    /**
+     * Persistence size budget (persistence redaction & budget, F27). Substrate honors
+     * `maxBytes` as a soft cap — a single artifact never exceeds
+     * the cap, and once the run's accumulated artifact bytes are
+     * within `maxBytes` of the cap, subsequent writes are redacted
+     * to a sentinel. `undefined` (the default) is unbounded — the
+     * host's storage policy takes over.
+     */
+    export interface ArtifactSizeBudget {
+      maxBytes?: number;
+    }
+
+    /**
+     * Which side of a node's I/O is being persisted (persistence redaction & budget).
+     * Substrate threads this through `artifactStore.writeArtifact`
+     * so the redaction policy can match against the offending
+     * surface (e.g. policy `'output'` redacts only output writes).
+     */
+    export type ArtifactSurface = 'input' | 'output' | 'meta';
+
+    /**
+     * Sentinel returned by the substrate when a write is redacted
+     * (persistence redaction & budget). Persisted in place of the plaintext payload so
+     * downstream audit consumers can see WHAT was redacted and WHY
+     * (policy match vs. size-budget exhaustion). Substrate refuses
+     * to silently drop content — every redaction is a marker.
+     */
+    export interface RedactionSentinel {
+      redacted: true;
+      reason: 'policy' | 'budget';
+      policy?: RedactionPolicy;
+      surface?: ArtifactSurface;
+      originalBytes?: number;
+    }
+
+    export interface ExecutionOverride {
+      timeoutMs?: number;
+      retry?: CapabilityRetryPolicy;
+      rateLimit?: CapabilityRateLimitPolicy;
+      concurrency?: CapabilityConcurrencyPolicy;
+    }
+
+    /**
+     * Standard execution event for observability (runtime-agnostic).
+     * Separate from compute.ExecutionEvent which is provider-specific.
+     * Used by Flow Engine to emit execution lifecycle events.
+     */
+    export type ExecutionEvent =
+      | {
+          type: 'span.start';
+          traceId: string;
+          spanId: string;
+          name: string;
+          ts: number;
+          data?: unknown;
+        }
+      | {
+          type: 'span.end';
+          traceId: string;
+          spanId: string;
+          ts: number;
+          ok: boolean;
+          error?: {
+            code: string;
+            message: string;
+          };
+        }
+      | {
+          type: 'retry';
+          traceId: string;
+          spanId: string;
+          attempt: number;
+          delayMs: number;
+          reason: string;
+        }
+      | {
+          type: 'rate_limited';
+          traceId: string;
+          spanId: string;
+          key: string;
+        }
+      | {
+          type: 'queue';
+          runId: string;
+          depth: number;
+          inFlight: number;
+        }
+      | {
+          type: 'cancelled';
+          runId: string;
+          mode: CancellationMode;
+          reason?: string;
+        };
+
+    export type ValidationSeverity = 'error' | 'warning';
+
+    export interface ValidationIssue {
+      path: string;
+      message: string;
+      severity: ValidationSeverity;
+      code?: string;
+    }
+
+    export interface ValidationResult {
+      ok: boolean;
+      errors: ValidationIssue[];
+      warnings: ValidationIssue[];
+    }
+
+    /**
+     * Validator API surface (host/extension implementation).
+     * Validates FlowBookDocument.
+     *
+     * `options.hasCapability` mirrors the top-level
+     * `validateFlowBookDocument` Trinity seam — implementers thread it
+     * into `flowBookValidator` so registry lookups stay pure and
+     * substitutable (capability registry + CONSTITUTION § 0.1).
+     */
+    export interface Validator {
+      validate(
+        spec: FlowBookDocument,
+        options?: {
+          mode?: 'strict' | 'best-effort';
+          hasCapability?: CapabilityLookup;
+        }
+      ): ValidationResult;
+    }
+
+    export const Validator: {
+      manager: Validator;
+    };
+
+    /**
+     * Validates a FlowBookDocument. Top-level helper exposed on `punica.flow`.
+     *
+     * Pass `options.hasCapability` to enable Trinity verification — the
+     * validator checks every `ivyNode` / `flowBook` `ref.id` against
+     * that predicate and emits `WF_UNKNOWN_CAPABILITY` errors (strict)
+     * or warnings (best-effort) for any miss. Substrate's
+     * `validator.module.ts` wires this to
+     * `unifiedCapabilityRegistry.getCapability(...)`. When omitted, the
+     * Trinity check is skipped (keeps the validator usable in
+     * registry-less unit tests).
+     */
+    export function validateFlowBookDocument(
+      spec: FlowBookDocument,
+      options?: {
+        mode?: 'strict' | 'best-effort';
+        hasCapability?: CapabilityLookup;
+      }
+    ): ValidationResult;
+
+    /**
+     * Cell-like primitives (portable, notebook-derived wins without "notebook as a product").
+     */
+    export type CellType = 'code' | 'markdown' | 'raw';
+    export type MultilineString = string | string[];
+
+    export interface CellMetadata {
+      ivy?: {
+        /**
+         * Optional annotation: which capability this cell belongs to (not required).
+         * Source-of-truth contract is CapabilityDefinition on IvyNode/FlowBook.
+         */
+        capability?: {
+          id?: CapabilityId;
+          version?: string;
+          [key: string]: unknown;
+        };
+        cell?: {
+          role?: 'input' | 'compute' | 'output';
+        };
+        [key: string]: unknown;
+      };
+      [key: string]: unknown;
+    }
+
+    export interface BaseOutput {
+      metadata?: JSONObject;
+    }
+
+    export interface StreamOutput extends BaseOutput {
+      output_type: 'stream';
+      name: 'stdout' | 'stderr';
+      text: MultilineString;
+    }
+
+    export interface DisplayDataOutput extends BaseOutput {
+      output_type: 'display_data';
+      data: JSONObject;
+    }
+
+    export interface ExecuteResultOutput extends BaseOutput {
+      output_type: 'execute_result';
+      data: JSONObject;
+      execution_count: number;
+    }
+
+    export interface ErrorOutput extends BaseOutput {
+      output_type: 'error';
+      ename: string;
+      evalue: string;
+      traceback: string[];
+    }
+
+    export interface ExtendedOutput extends BaseOutput {
+      output_type: string;
+      status?: 'ok' | 'error';
+      comm_id?: string;
+      method?: string;
+      execution_state?: string;
+      name?: string;
+      text?: MultilineString;
+      value?: JSONValue;
+      title?: string;
+      isDone?: boolean;
+      [key: string]: JSONValue | undefined;
+    }
+
+    export type Output =
+      | StreamOutput
+      | DisplayDataOutput
+      | ExecuteResultOutput
+      | ErrorOutput
+      | ExtendedOutput;
+
+    export interface Cell {
+      id: string;
+      cell_type: CellType;
+      source: MultilineString;
+      metadata: CellMetadata;
+      /**
+       * Optional execution fields, mirroring notebook.CodeCell for reuse.
+       * These are primarily useful when reusing runtime outputs in ivy graphs.
+       */
+      execution_count?: number | null;
+      outputs?: Output[];
+    }
+
+    export interface Program {
+      format: 'cells';
+      language: 'python' | string;
+      cells: Cell[];
+      roles?: {
+        inputCellId?: string;
+        outputCellId?: string;
+      };
+      extras?: JSONObject;
+    }
+
+    /**
+     * Capability ID (IvyNode and FlowBook are both CapabilityDefinition-based).
+     */
+    export type CapabilityId = string;
+
+    /**
+     * IvyNode definition (atomic executable building block).
+     */
+    export interface NodeDefinition extends CapabilityDefinition {
+      apiVersion: 'ivy.node/v0.2';
+      kind: 'IvyNode';
+      program: Program;
+      /**
+       * Runtime contract for Python or other backends.
+       * Concrete runtimes can extend/interpret these fields as needed.
+       */
+      runtime?: {
+        module?: string;
+        function?: string;
+        config?: JSONObject;
+        kind?: string;
+      };
+      /**
+       * Inline test specification for this Ivy node (quality gates / selection).
+       * For external test specifications, use testSpecificationIds.
+       */
+      tests?: TestSpec;
+      /**
+       * Test specification IDs associated with this node
+       * Format: "test.{capabilityId}" (e.g., "test.ivy.node.http.fetch")
+       */
+      testSpecificationIds?: TestSpecificationId[];
+      extras?: JSONObject;
+    }
+
+    /**
+     * -------------------------
+     * Generic graph IR (the core)
+     * -------------------------
+     * Used by FlowBook now; intended to be reused by agent/mcp/rest later.
+     */
+    export type GraphId = string;
+    export type NodeId = string;
+
+    /**
+     * Edge mapping uses *Path (string).
+     * Convention: dot-path (e.g. "text", "result.value").
+     */
+    export interface Edge {
+      fromId: NodeId;
+      toId: NodeId;
+      fromPath?: string;
+      toPath?: string;
+      metadata?: JSONObject;
+    }
+
+    export interface Graph {
+      entryNodeId: NodeId;
+      nodes: Node[];
+      edges: Edge[];
+      runBudget?: RunBudget;
+      config?: JSONObject;
+    }
+
+    /**
+     * Node.defaults are fallback values when no incoming edge provides that field.
+     * Precedence (intended): incoming edge value > defaults > undefined
+     */
+    export interface Node {
+      id: NodeId;
+      label?: string;
+      disabled?: boolean;
+      ref: NodeRef;
+      defaults?: JSONObject;
+      executionOverride?: ExecutionOverride;
+      data?: JSONObject;
+      /**
+       * Per-node redaction policy (persistence redaction & budget). When set, the
+       * substrate redacts the matching surface(s) before any
+       * artifact persistence write. Intersects with the
+       * capability's declared `dataClassification` — substrate
+       * picks the strictest of the two so a "sensitive" capability
+       * cannot be widened to plaintext by a node-level `'none'`
+       * override.
+       *
+       *  - `'none'`   — no redaction (substrate default).
+       *  - `'input'`  — redact node input payloads.
+       *  - `'output'` — redact node output payloads.
+       *  - `'all'`    — redact both.
+       */
+      redactionPolicy?: RedactionPolicy;
+    }
+
+    /**
+     * Reserved pseudo IO node ids (for FlowBook wiring).
+     * If edges use these ids, they must exist as nodes in Graph.nodes.
+     */
+    export type FlowIoNodeId = 'flow-input' | 'flow-output';
+
+    export interface FlowInputRef {
+      kind: 'flowInput';
+    }
+
+    export interface FlowOutputRef {
+      kind: 'flowOutput';
+    }
+
+    export interface NodeCapabilityRef {
+      kind: 'ivyNode';
+      id: CapabilityId;
+      version?: string;
+    }
+
+    export interface FlowBookRef {
+      kind: 'flowBook';
+      id: CapabilityId;
+      version?: string;
+      /**
+       * Optional inline definition for local experiments (no registry publishing).
+       */
+      inline?: FlowBookDocument;
+    }
+
+    /**
+     * Discriminator for substrate-built primitive nodes (flow primitives).
+     * The `primitive` field tags the executor; the matching `node.data`
+     * payload is one of the `*PrimitiveData` shapes declared alongside
+     * `FlowPrimitiveKind` in `punica.module.flow.primitives.d.ts`.
+     *
+     * Body execution (loop body, try/catch handler, etc.) is wired
+     * through `flow.runSubflow` (subflow spawning); 4.C executors evaluate
+     * predicates / collections / lambdas + emit decision artifacts and
+     * forward-defer the actual body invocation.
+     */
+    export interface PrimitiveRef {
+      kind: 'primitive';
+      primitive: FlowPrimitiveKind;
+    }
+
+    export type NodeRef =
+      | FlowInputRef
+      | FlowOutputRef
+      | NodeCapabilityRef
+      | FlowBookRef
+      | PrimitiveRef;
+
+    /**
+     * GraphDocumentBase: generic capability-backed graph.
+     */
+    export interface GraphDocumentBase extends CapabilityDefinition {
+      graph: Graph;
+      view?: ViewMetadata;
+      extras?: JSONObject;
+    }
+
+    /**
+     * FlowBook = GraphDocumentBase with FlowBook discriminators.
+     */
+    export interface FlowBookDocument extends GraphDocumentBase {
+      apiVersion: 'ivy.flowbook/v0.1';
+      kind: 'FlowBook';
+    }
+
+    /**
+     * Edge reference used in notebook metadata (metadata.ivy.flow.edges).
+     * This is a legacy format used for notebook-based workflows.
+     */
+    export interface FlowEdgeRef {
+      fromId: string;
+      toId: string;
+      fromProperty?: string;
+      toProperty?: string;
+      metadata?: JSONObject;
+    }
+  }
+
+  // Module-level export for convenience
+  export type FlowEdgeRef = flow.FlowEdgeRef;
+}

package/types/punica.module.flow.engine.d.ts

@@ -0,0 +1,228 @@
+/// <reference path="./punica.module.flow.d.ts" />
+
+declare module 'punica' {
+  export namespace flow {
+    export namespace engine {
+      export type RunStatus =
+        | 'QUEUED'
+        | 'RUNNING'
+        | 'WAITING_APPROVAL'
+        | 'PAUSED'
+        | 'RETRYING'
+        | 'COMPLETED'
+        | 'FAILED'
+        | 'CANCELLED';
+
+      /**
+       * Substrate-pinned terminal `RunStatus` values (run status / checkpoints). A
+       * run in any of these states never transitions again; the state
+       * machine refuses every outgoing edge from terminal nodes. The
+       * literal-union shape is here so consumers can narrow without
+       * importing the runtime state machine.
+       */
+      export type TerminalRunStatus = 'COMPLETED' | 'FAILED' | 'CANCELLED';
+
+      /**
+       * Pure run-status state machine (run status / checkpoints). Substrate's
+       * authoritative transition graph — every status mutation must
+       * route through `assertTransition` so F21 (invalid transition
+       * detection) is enforced uniformly across the engine.
+       *
+       *  - `canTransitionTo(current, next)` — predicate, never throws.
+       *  - `assertTransition(current, next)` — throws on invalid edge.
+       *  - `getValidTransitions(current)` — outgoing edges for tooling.
+       *  - `isTerminal(status)` — short-circuit guard.
+       */
+      export interface RunStatusStateMachine {
+        canTransitionTo(current: RunStatus, next: RunStatus): boolean;
+        assertTransition(current: RunStatus, next: RunStatus): void;
+        getValidTransitions(current: RunStatus): readonly RunStatus[];
+        isTerminal(status: RunStatus): status is TerminalRunStatus;
+      }
+
+      /**
+       * Substrate-shipped singleton — pure state machine, no
+       * dependencies. Exposed at `punica.flow.engine.statusStateMachine`.
+       */
+      export const statusStateMachine: RunStatusStateMachine;
+
+      /**
+       * Canvas-facing node status vocabulary produced by
+       * `subscribeNodeStatuses` (the single event→status choke point).
+       */
+      export type NodeCanvasStatus =
+        | 'waiting'
+        | 'running'
+        | 'completed'
+        | 'error';
+
+      export interface NodeStatusUpdate {
+        nodeId: string;
+        status: NodeCanvasStatus;
+        runId: string | null;
+        /**
+         * True on the first update of a new run — subscribers should reset
+         * all their nodes to `waiting` before applying this update.
+         */
+        isNewRun: boolean;
+        /** Raw engine StepStatus (e.g. 'RUNNING', 'SUCCESS'). */
+        stepStatus: string;
+      }
+
+      /**
+       * Subscribe to live node statuses projected from
+       * `workflow.stepStarted/stepUpdated/stepFinished`. Events whose
+       * step id is not in `nodeIds` are dropped, so concurrent runs of
+       * unrelated flows never cross-update a subscriber. Exposed at
+       * `punica.flow.engine.subscribeNodeStatuses`. Returns a disposer.
+       */
+      export function subscribeNodeStatuses(
+        options: { nodeIds: readonly string[] },
+        callback: (update: NodeStatusUpdate) => void
+      ): () => void;
+
+      export type StepStatus =
+        | 'PENDING'
+        | 'RUNNING'
+        | 'WAITING_APPROVAL'
+        | 'PAUSED'
+        | 'RETRYING'
+        | 'SUCCESS'
+        | 'FAILED'
+        | 'CANCELLED'
+        | 'SKIPPED';
+
+      export type ArtifactType = 'text' | 'json' | 'file' | 'patch' | 'log';
+
+      export interface ArtifactRecord {
+        id: string;
+        runId: string;
+        stepId: string;
+        type: ArtifactType;
+        createdAtMs: number;
+        name?: string;
+        mimeType?: string;
+        uri?: string;
+        preview?: string;
+        sizeBytes?: number;
+        meta?: Record<string, unknown>;
+      }
+
+      export interface PendingApprovalRecord {
+        pendingId: string;
+        attemptCorrelationId: string;
+        kind: string;
+        id: string;
+        risk: string;
+        approval: string;
+        reason?: string;
+        workspaceId?: string;
+        timestampMs: number;
+      }
+
+      export interface StepRecord {
+        stepId: string; // node.id
+        nodeId: string;
+        nodeType: string; // Derived from flow.NodeRef.kind: 'capability.call' | 'workflow.run' | 'flow.input' | 'flow.output' | 'unknown'
+        attempt: number;
+        status: StepStatus;
+        startedAtMs?: number;
+        endedAtMs?: number;
+        cellId?: string;
+        attemptCorrelationId?: string;
+        spanId?: string;
+        error?: { message: string; code?: string };
+        inputsPreview?: string;
+        outputsPreview?: string;
+        artifactIds?: string[];
+        approval?: {
+          pendingId?: string;
+          required?: boolean;
+          requestedAtMs?: number;
+          resolved?: boolean;
+          decision?: 'approved' | 'rejected';
+        };
+      }
+
+      export interface RunRecord {
+        runId: string;
+        specVersion: '0.1'; // Legacy field, kept for compatibility
+        status: RunStatus;
+        createdAtMs: number;
+        startedAtMs?: number;
+        endedAtMs?: number;
+        traceId: string;
+        entryNodeId: string;
+        metadata?: { title?: string; tags?: string[] };
+        currentNodeId?: string;
+        error?: { message: string; nodeId?: string; correlationId?: string };
+        steps: StepRecord[];
+      }
+
+      export interface RunSummary {
+        runId: string;
+        status: RunStatus;
+        createdAtMs: number;
+        startedAtMs?: number;
+        endedAtMs?: number;
+        traceId: string;
+        metadata?: { title?: string };
+      }
+
+      export interface StartRunInput {
+        spec: flow.FlowBookDocument;
+        workspaceId?: string;
+        filePathOrUri?: string;
+        /**
+         * Optional run-level input payload. Exposed to the graph via the
+         * `flowInput` pseudo-node's output, so downstream nodes can read it
+         * through edge wiring (`edge.fromId === 'flow-input'`, `fromPath`).
+         */
+        input?: flow.JSONValue;
+      }
+
+      export interface EngineApi {
+        initialize(): void;
+        startRun(input: StartRunInput): Promise<{ runId: string }>;
+        pauseRun(runId: string): Promise<boolean>;
+        resumeRun(runId: string): Promise<boolean>;
+        cancelRun(
+          runId: string,
+          mode?: flow.CancellationMode
+        ): Promise<boolean>;
+        getRun(runId: string): RunRecord | null;
+        /**
+         * Read a node's recorded output for a run (e.g. `'flow-output'` for
+         * the flow's assembled result). Returns `undefined` for unknown
+         * runs/nodes. Full JSON value — unlike `StepRecord.outputsPreview`,
+         * which is a truncated display string.
+         */
+        getNodeOutput(
+          runId: string,
+          nodeId: string
+        ): flow.JSONValue | undefined;
+        listRuns(options?: {
+          status?: RunStatus;
+          limit?: number;
+        }): RunSummary[];
+        approvePending(input: {
+          pendingId: string;
+          scope: kernel.ApprovalScope;
+        }): boolean;
+        rejectPending(input: { pendingId: string }): boolean;
+        /**
+         * Spawn a child run for a `FlowBookDocument` and await its
+         * terminal state (subflow spawning). Substrate enforces
+         * `MAX_SUBFLOW_DEPTH` and rejects synchronously when
+         * `(parentDepth ?? 0) + 1` exceeds the cap. The child run
+         * inherits the parent's `workspaceId` so the policy store's
+         * `'once'` approval scope (D5) deduplicates naturally —
+         * F33 dedup is structural, not a separate cache.
+         */
+        runSubflow(input: flow.SubflowInvocation): Promise<flow.SubflowResult>;
+      }
+
+      export const manager: EngineApi;
+    }
+  }
+}