@kubun/plugin-workflow-api 0.14.1 → 0.16.0

package/lib/index.d.ts

@@ -38,6 +38,10 @@ export type WorkflowDefinition<State extends Record<string, unknown> = Record<st
     retry?: RetryPolicy;
     onTerminal?: (info: TerminalInfo) => void;
     managed?: boolean;
+    remote?: {
+        observe?: boolean;
+        command?: boolean;
+    };
 };
 export type WorkflowEvents = {
     started: {
@@ -85,6 +89,10 @@ export type ListFilter = {
     queue?: string;
     status?: WorkflowStatus;
 };
+export declare const RETRY_REFUSAL_REASONS: readonly ["not_found", "not_failed", "no_next_action", "singleton"];
+export type RetryRefusalReason = (typeof RETRY_REFUSAL_REASONS)[number];
+export declare const COMMAND_REFUSAL_REASONS: readonly ["not_commandable", "not_found", "not_failed", "no_next_action", "singleton"];
+export type CommandRefusalReason = (typeof COMMAND_REFUSAL_REASONS)[number];
 export type QueueOptions = {
     concurrency: number;
     ratePerMinute?: number;
@@ -112,6 +120,8 @@ export type PeriodicSync = {
 export type WorkflowAPI = {
     register<State extends Record<string, unknown>, Handlers extends HandlersRecord<State> = HandlersRecord<State>>(def: WorkflowDefinition<State, Handlers>): void;
     isManagedWorkflow(name: string): boolean;
+    isRemotelyObservable(name: string): boolean;
+    isRemotelyCommandable(name: string): boolean;
     defineQueue(name: string, opts: QueueOptions): void;
     enqueue(name: string, params?: unknown, opts?: EnqueueOptions): Promise<InstanceHandle>;
     schedule(name: string, params: unknown, when: ScheduleSpec): Promise<ScheduleHandle>;
@@ -121,6 +131,7 @@ export type WorkflowAPI = {
         reactivate?: boolean;
     }): Promise<ScheduleHandle>;
     cancel(instanceID: string): Promise<void>;
+    retry(instanceID: string): Promise<InstanceStatus>;
     get(instanceID: string): Promise<InstanceStatus | null>;
     list(filter?: ListFilter): Promise<Array<InstanceStatus>>;
     getCurrentInstance(name: string, singletonKey: string): Promise<InstanceStatus | null>;

package/lib/index.js

@@ -4,4 +4,34 @@
 // runtime edge on the workflow plugin, so a consumer stays independently
 // loadable. The plugin implements these; the pure policy math and `defineWorkflow`
 // stay in @kubun/plugin-workflow.
-export { };
+// Why an operator retry refused, when it did not re-arm. Never a silent false
+// success: `retry` throws a typed error carrying one of these.
+// - `not_found`: no instance with that id.
+// - `not_failed`: the instance is not in `failed` (already re-armed, running,
+//   or terminal-completed/cancelled) — includes losing the race to a concurrent
+//   retry that flipped it out of `failed` first.
+// - `no_next_action`: a failed row with no resumable action; re-arming it would
+//   fabricate an entry point, so it is refused rather than restarted.
+// - `singleton`: a live (pending/running) instance already holds the same
+//   (name, singletonKey); re-arming would create a second live singleton.
+//
+// Runtime const, not just a type: consumers that cannot value-import the engine
+// (e.g. plugin-p2p's type-only boundary) still need the exact reason set at
+// runtime to recover a structurally-caught refusal, so this is the one place
+// that set is spelled out.
+export const RETRY_REFUSAL_REASONS = [
+    'not_found',
+    'not_failed',
+    'no_next_action',
+    'singleton'
+];
+// The full reason set a DIRECTED group command can refuse with: the engine's own
+// retry refusals plus `not_commandable`, which only the p2p command boundary
+// raises (a workflow that did not opt into remote command). Single-sourced here so
+// the p2p wire schema and the caller-facing contract type both derive from ONE
+// list and cannot drift — the wire enum spreads this, the contract's reason type
+// aliases CommandRefusalReason.
+export const COMMAND_REFUSAL_REASONS = [
+    'not_commandable',
+    ...RETRY_REFUSAL_REASONS
+];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubun/plugin-workflow-api",
-  "version": "0.14.1",
+  "version": "0.16.0",
   "keywords": [],
   "license": "see LICENSE.md",
   "sideEffects": false,
@@ -15,7 +15,7 @@
     "LICENSE.md"
   ],
   "dependencies": {
-    "@kubun/store-workflow": "^0.14.1",
+    "@kubun/store-workflow": "^0.16.0",
     "@sozai/event": "^0.1.3",
     "@sozai/flow": "^0.3.1",
     "@sozai/schema": "^0.1.2"