@voltro/protocol 0.85.0 → 0.87.0

package/dist/workflow.js

@@ -0,0 +1,297 @@
+import { strictInput as e } from "./strictInput.js";
+import { defineAction as t, defineQuery as n, hasEnforcedGuard as r, workflowWireErrorUnion as i } from "./procedure.js";
+import { getWorkflowAccess as a } from "./workflowAccess.js";
+import { WorkflowStartTerminalOutcomeSchema as o } from "./workflowStartOutcome.js";
+import { Schema as s } from "effect";
+import { Rpc as c } from "effect/rpc";
+//#region src/workflow.ts
+var l = s.Literals([
+	"running",
+	"succeeded",
+	"failed",
+	"cancelled",
+	"suspended"
+]), u = s.Struct({
+	id: s.String,
+	workflowName: s.String,
+	executionId: s.String,
+	status: s.Union([l, s.Literal("unknown")]),
+	output: s.optional(s.Unknown),
+	error: s.optional(s.Struct({
+		tag: s.NullOr(s.String),
+		message: s.String
+	}))
+}), d = s.Struct({
+	operation: s.Literals(["cancel", "resume"]),
+	kind: s.Literals([
+		"accepted",
+		"confirmed",
+		"unknown",
+		"already-terminal"
+	]),
+	requestId: s.NullOr(s.NonEmptyString),
+	snapshot: u
+}).pipe(s.check(s.makeFilter((e) => e.kind === "unknown" ? !0 : e.kind === "accepted" ? e.requestId !== null && (e.snapshot.status === "running" || e.snapshot.status === "suspended") : e.kind === "already-terminal" ? e.snapshot.status === "succeeded" || e.snapshot.status === "failed" || e.snapshot.status === "cancelled" : e.operation === "cancel" ? e.snapshot.status === "cancelled" : e.requestId !== null && e.snapshot.status === "running", { message: "Workflow control acknowledgement contradicts its observed state or receipt identity" }))), f = s.Struct({
+	operation: s.Literal("cancel"),
+	workflowName: s.NonEmptyString,
+	receiptId: s.NonEmptyString,
+	requestId: s.NullOr(s.NonEmptyString),
+	kind: s.Literals([
+		"accepted",
+		"confirmed",
+		"unknown",
+		"already-terminal"
+	]),
+	observation: s.Union([
+		s.Struct({ kind: s.Literal("pending") }),
+		s.Struct({
+			kind: s.Literal("admission"),
+			outcome: s.Union([o, s.Struct({
+				kind: s.Literal("rejected"),
+				failureId: s.NonEmptyString
+			})])
+		}),
+		s.Struct({
+			kind: s.Literal("execution"),
+			snapshot: u
+		}),
+		s.Struct({
+			kind: s.Literal("unavailable"),
+			reason: s.Literals([
+				"missing-request",
+				"missing-run",
+				"unconfirmed-generation",
+				"unbound-submission"
+			])
+		})
+	])
+}).pipe(s.check(s.makeFilter((e) => {
+	let t = e.observation;
+	if (t.kind === "unavailable") return e.kind === "unknown" && (t.reason === "missing-request" ? e.requestId === null : e.requestId !== null);
+	if (e.requestId === null) return !1;
+	if (t.kind === "pending") return e.kind === "accepted";
+	if (t.kind === "admission") return e.kind === (t.outcome.kind === "cancelled" ? "confirmed" : "already-terminal");
+	let n = t.snapshot;
+	return n.workflowName !== e.workflowName || n.id.length === 0 || n.executionId.length === 0 ? !1 : e.kind === "accepted" ? n.status === "running" || n.status === "suspended" : e.kind === "confirmed" ? n.status === "cancelled" : e.kind === "already-terminal" && (n.status === "succeeded" || n.status === "failed" || n.status === "cancelled");
+}, { message: "Queued cancellation acknowledgement contradicts its receipt or observation" }))), p = s.Literals([
+	"cancel",
+	"terminate",
+	"abandon"
+]), m = s.Struct({
+	mode: s.String,
+	dueAt: s.NullOr(s.Number),
+	retryAfterMs: s.NullOr(s.Number),
+	intentId: s.NullOr(s.String)
+}), h = s.Struct({
+	id: s.String,
+	workflowName: s.String,
+	executionId: s.NullOr(s.String),
+	status: s.Literals([
+		"running",
+		"succeeded",
+		"queued",
+		"dropped",
+		"skipped",
+		"replayed"
+	]),
+	deferral: s.optional(m)
+}), g = (t, n) => {
+	let o = a(t);
+	return c.make(t.name, {
+		payload: e(t.payloadSchema, t.name, r(o.guards)),
+		success: h,
+		error: i({
+			errorSchema: t.errorSchema,
+			guards: o.guards
+		}, n)
+	});
+}, _ = s.Struct({
+	id: s.String,
+	tag: s.String,
+	executionId: s.String,
+	status: l,
+	payload: s.Unknown,
+	workflowVersion: s.NullOr(s.String),
+	workflowPatches: s.NullOr(s.Unknown),
+	output: s.NullOr(s.Unknown),
+	subject: s.NullOr(s.Unknown),
+	source: s.NullOr(s.String),
+	errorTag: s.NullOr(s.String),
+	errorMessage: s.NullOr(s.String),
+	cancelled: s.Boolean,
+	startedAt: s.DateFromString,
+	completedAt: s.NullOr(s.DateFromString),
+	durationMs: s.NullOr(s.Number),
+	traceId: s.NullOr(s.String),
+	parentExecutionId: s.NullOr(s.String),
+	parentClosePolicy: s.NullOr(p)
+}), v = s.Struct({
+	tag: s.optional(s.String),
+	status: s.optional(l),
+	limit: s.optional(s.Number)
+}), y = s.Struct({
+	id: s.String,
+	runId: s.String,
+	stepName: s.String,
+	attempt: s.Number,
+	status: s.Literals([
+		"running",
+		"succeeded",
+		"failed"
+	]),
+	input: s.NullOr(s.Unknown),
+	retryPolicy: s.NullOr(s.Unknown),
+	output: s.NullOr(s.Unknown),
+	errorTag: s.NullOr(s.String),
+	errorMessage: s.NullOr(s.String),
+	errorCause: s.NullOr(s.Unknown),
+	startedAt: s.DateFromString,
+	completedAt: s.NullOr(s.DateFromString),
+	durationMs: s.NullOr(s.Number)
+}), b = s.Struct({
+	id: s.String,
+	runId: s.String,
+	eventType: s.String,
+	payload: s.NullOr(s.Unknown),
+	occurredAt: s.DateFromString,
+	stepName: s.NullOr(s.String),
+	attempt: s.NullOr(s.Number)
+}), x = s.Struct({
+	id: s.String,
+	name: s.String,
+	payload: s.Unknown,
+	source: s.String,
+	subject: s.NullOr(s.Unknown),
+	traceId: s.NullOr(s.String),
+	occurredAt: s.DateFromString
+}), S = s.Struct({
+	id: s.String,
+	eventId: s.String,
+	eventName: s.String,
+	triggerId: s.String,
+	workflowName: s.String,
+	executionId: s.NullOr(s.String),
+	status: s.Literals([
+		"starting",
+		"started",
+		"skipped",
+		"failed"
+	]),
+	idempotencyKey: s.String,
+	skipped: s.Boolean,
+	errorMessage: s.NullOr(s.String),
+	createdAt: s.DateFromString,
+	completedAt: s.NullOr(s.DateFromString)
+}), C = s.Struct({ id: s.String }), w = s.Struct({ runId: s.String }), T = s.Struct({
+	name: s.optional(s.String),
+	limit: s.optional(s.Number)
+}), E = s.Struct({ eventId: s.String }), D = s.Struct({
+	requestId: s.NonEmptyString,
+	cause: s.optionalKey(s.Struct({
+		reason: s.NonEmptyString,
+		detail: s.optional(s.Record(s.String, s.Unknown))
+	}))
+}), O = s.Struct({
+	workflowName: s.String,
+	executionId: s.String,
+	control: s.optional(D)
+}), k = s.Struct({
+	workflowName: s.NonEmptyString,
+	executionId: s.NonEmptyString,
+	operation: s.Literals(["cancel", "resume"]),
+	requestId: s.NonEmptyString
+}), A = s.Struct({
+	workflowName: s.NonEmptyString,
+	receiptId: s.NonEmptyString,
+	requestId: s.NonEmptyString
+}), j = s.Struct({
+	...A.fields,
+	cause: D.fields.cause
+}), M = t({
+	name: "__voltro.workflow.queued.cancel",
+	input: j,
+	output: f,
+	openAccess: "authorization happens in the executor against the target run — the caller must be authenticated and belong to the run's tenant, and a missing run answers exactly like a foreign one"
+}), N = n({
+	name: "__voltro.workflow.queued.control",
+	input: A,
+	output: f,
+	openAccess: "authorization happens in the executor against the target run — the caller must be authenticated and belong to the run's tenant, and a missing run answers exactly like a foreign one"
+}), P = n({
+	name: "__voltro.workflow.control",
+	input: k,
+	output: d,
+	openAccess: "authorization happens in the executor against the target run — the caller must be authenticated and belong to the run's tenant, and a missing run answers exactly like a foreign one"
+}), F = s.Struct({
+	id: s.String,
+	signalName: s.String,
+	payload: s.optional(s.Unknown)
+}), I = s.Struct({
+	id: s.String,
+	updateName: s.String,
+	payload: s.optional(s.Unknown),
+	timeoutMs: s.optional(s.Number)
+}), L = s.Struct({
+	eventId: s.String,
+	updateId: s.String,
+	completedEventId: s.String,
+	result: s.Unknown
+}), R = n({
+	name: "__voltro.workflow.run",
+	source: "_voltro_workflow_runs",
+	input: C,
+	output: s.Array(_),
+	openAccess: "the answer is scoped to the caller in the executor — a system or admin:full subject sees every row, an authenticated subject the rows of its own tenant, an anonymous caller none"
+}), z = n({
+	name: "__voltro.workflow.runs",
+	source: "_voltro_workflow_runs",
+	input: v,
+	output: s.Array(_),
+	openAccess: "the answer is scoped to the caller in the executor — a system or admin:full subject sees every row, an authenticated subject the rows of its own tenant, an anonymous caller none"
+}), B = n({
+	name: "__voltro.workflow.run.steps",
+	source: "_voltro_workflow_run_steps",
+	input: w,
+	output: s.Array(y),
+	openAccess: "the answer is scoped to the caller in the executor — a system or admin:full subject sees every row, an authenticated subject the rows of its own tenant, an anonymous caller none"
+}), V = n({
+	name: "__voltro.workflow.run.events",
+	source: "_voltro_workflow_run_events",
+	input: w,
+	output: s.Array(b),
+	openAccess: "the answer is scoped to the caller in the executor — a system or admin:full subject sees every row, an authenticated subject the rows of its own tenant, an anonymous caller none"
+}), H = n({
+	name: "__voltro.workflow.domainEvents",
+	source: "_voltro_workflow_events",
+	input: T,
+	output: s.Array(x),
+	openAccess: "the answer is scoped to the caller in the executor — a system or admin:full subject sees every row, an authenticated subject the rows of its own tenant, an anonymous caller none"
+}), U = n({
+	name: "__voltro.workflow.event.deliveries",
+	source: "_voltro_workflow_event_deliveries",
+	input: E,
+	output: s.Array(S),
+	openAccess: "the answer is scoped to the caller in the executor — a system or admin:full subject sees every row, an authenticated subject the rows of its own tenant, an anonymous caller none"
+}), W = t({
+	name: "__voltro.workflow.cancel",
+	input: O,
+	output: d,
+	openAccess: "authorization happens in the executor against the target run — the caller must be authenticated and belong to the run's tenant, and a missing run answers exactly like a foreign one"
+}), G = t({
+	name: "__voltro.workflow.resume",
+	input: O,
+	output: d,
+	openAccess: "authorization happens in the executor against the target run — the caller must be authenticated and belong to the run's tenant, and a missing run answers exactly like a foreign one"
+}), K = t({
+	name: "__voltro.workflow.signal",
+	input: F,
+	output: s.Struct({ eventId: s.String }),
+	openAccess: "authorization happens in the executor against the target run — the caller must be authenticated and belong to the run's tenant, and a missing run answers exactly like a foreign one"
+}), q = t({
+	name: "__voltro.workflow.update",
+	input: I,
+	output: L,
+	openAccess: "authorization happens in the executor against the target run — the caller must be authenticated and belong to the run's tenant, and a missing run answers exactly like a foreign one"
+});
+//#endregion
+export { O as WorkflowControlInputSchema, D as WorkflowControlIntentSchema, k as WorkflowControlReadInputSchema, d as WorkflowControlResultSchema, x as WorkflowDomainEventRowSchema, T as WorkflowDomainEventsInputSchema, E as WorkflowEventDeliveriesInputSchema, S as WorkflowEventDeliveryRowSchema, p as WorkflowParentClosePolicySchema, j as WorkflowQueuedCancelInputSchema, f as WorkflowQueuedCancellationResultSchema, A as WorkflowQueuedControlTargetSchema, b as WorkflowRunEventRowSchema, h as WorkflowRunHandleSchema, C as WorkflowRunRefSchema, _ as WorkflowRunRowSchema, u as WorkflowRunSnapshotSchema, l as WorkflowRunStatusSchema, y as WorkflowRunStepRowSchema, w as WorkflowRunTableRefSchema, v as WorkflowRunsInputSchema, F as WorkflowSignalInputSchema, m as WorkflowStartDeferralSchema, I as WorkflowUpdateInputSchema, L as WorkflowUpdateResultSchema, W as workflowCancelDescriptor, P as workflowControlQueryDescriptor, H as workflowDomainEventsQueryDescriptor, U as workflowEventDeliveriesQueryDescriptor, M as workflowQueuedCancelDescriptor, N as workflowQueuedControlQueryDescriptor, G as workflowResumeDescriptor, V as workflowRunEventsQueryDescriptor, R as workflowRunQueryDescriptor, B as workflowRunStepsQueryDescriptor, z as workflowRunsQueryDescriptor, K as workflowSignalDescriptor, g as workflowToRpc, q as workflowUpdateDescriptor };

package/dist/workflowAccess.js

@@ -0,0 +1,61 @@
+import { openAccessSpec as e } from "./scopes.js";
+//#region src/workflowAccess.ts
+var t = Symbol.for("@voltro/protocol/workflow-access"), n = {
+	guards: void 0,
+	openAccess: void 0,
+	internal: !1,
+	controls: void 0,
+	controlsOpenAccess: void 0
+}, r = (t, n) => {
+	let r = n.guards;
+	if (r !== void 0 && r.length === 0) throw Error(`workflow("${t}"): \`guards: []\` is empty, so it enforces nothing —\n  but it reads at the call site as if the start were protected. Omit the field
+  and decide with \`openAccess\` or \`internal\`, or list the scopes that may start it.`);
+	if (n.openAccess !== void 0) {
+		if (n.openAccess.trim() === "") throw Error(`workflow("${t}"): \`openAccess\` needs a REASON, not an empty string. It is\n  the sentence a reviewer reads to decide whether anyone should really be able to
+  start durable work without an authorization check — e.g. \`openAccess: 'public
+  newsletter signup; the payload carries only the address being confirmed'\`.`);
+		if (r !== void 0 && r.length > 0) throw Error(`workflow("${t}"): \`openAccess\` and \`guards\` are two different access\n  decisions, so declaring both says the start is protected AND open. Keep the
+  guards if a caller must hold a scope; drop them if anyone may start it.`);
+		if (n.internal === !0) throw Error(`workflow("${t}"): \`internal: true\` cannot be combined with \`openAccess\`.\n  \`internal\` takes the start OFF the wire, and \`openAccess\` declares who may
+  start it over the wire — a decision about a door that does not exist. Drop
+  \`openAccess\` (an internal workflow needs no wire decision), or drop
+  \`internal: true\` if the workflow really is meant to be startable by clients.`);
+	}
+	let i = n.controls?.guards, a = n.controls?.openAccess;
+	if (i !== void 0 && i.length === 0) throw Error(`workflow("${t}"): \`controls: { guards: [] }\` is empty, so it enforces nothing —\n  but it reads at the call site as if driving this run were protected. Omit
+  \`controls\` (wire control is then refused for everyone but \`admin:full\`), or
+  list the scopes a caller needs to cancel or signal a run.`);
+	if (a !== void 0) {
+		if (a.trim() === "") throw Error(`workflow("${t}"): \`controls: { openAccess }\` needs a REASON, not an empty string.\n  It is the sentence a reviewer reads to decide whether anyone who can see this
+  run should be able to cancel or signal it — e.g. \`controls: { openAccess:
+  'the run belongs to the caller who started it; cancelling it affects nobody else' }\`.`);
+		if (i !== void 0 && i.length > 0) throw Error(`workflow("${t}"): \`controls\` takes \`guards\` OR \`openAccess\`, not both.\n  Two answers to one question; keep the guards if a caller needs a scope.`);
+	}
+	return {
+		guards: n.openAccess === void 0 ? n.guards : [e(n.openAccess.trim())],
+		openAccess: n.openAccess?.trim(),
+		internal: n.internal === !0,
+		controls: a === void 0 ? i : [e(a.trim())],
+		controlsOpenAccess: a?.trim()
+	};
+}, i = (e, n) => {
+	Object.defineProperty(e, t, {
+		value: n,
+		enumerable: !1
+	});
+}, a = (e) => {
+	if (typeof e != "object" && typeof e != "function" || e === null) return n;
+	let r = e[t];
+	return r === void 0 ? n : r;
+}, o = (e) => {
+	let t = a(e);
+	return {
+		name: e.name,
+		internal: t.internal,
+		guards: t.guards,
+		openAccess: t.openAccess,
+		controls: t.controls
+	};
+};
+//#endregion
+export { t as WorkflowAccessProperty, i as attachWorkflowAccess, a as getWorkflowAccess, r as resolveWorkflowAccess, o as workflowAccessDescriptor };

package/dist/workflowRestart.js

@@ -0,0 +1,45 @@
+import { Schema as e } from "effect";
+//#region src/workflowRestart.ts
+var t = e.NonEmptyString.pipe(e.check(e.makeFilter((e) => e.trim().length > 0, { message: "A workflow restart identity must not be blank" }))), n = e.Union([e.Struct({ kind: e.Literal("failed-steps") }), e.Struct({
+	kind: e.Literal("from-step"),
+	stepName: t
+})]), r = e.Struct({
+	requestId: t.pipe(e.check(e.isMaxLength(64))),
+	runId: t
+}), i = e.Struct({
+	...r.fields,
+	selection: n
+}), a = {
+	...i.fields,
+	workflowName: t,
+	executionId: t,
+	originalGeneration: t,
+	requestedAt: e.Number.pipe(e.check(e.isFinite())),
+	dispatchAttempts: e.Number.check(e.isInt(), e.isGreaterThanOrEqualTo(0))
+}, o = e.Union([
+	e.Struct({
+		...r.fields,
+		kind: e.Literal("not-found")
+	}),
+	e.Struct({
+		...i.fields,
+		kind: e.Literal("withdrawn"),
+		workflowName: t,
+		withdrawnAt: e.Number.pipe(e.check(e.isFinite()))
+	}),
+	e.Struct({
+		...a,
+		kind: e.Literal("pending")
+	}),
+	e.Struct({
+		...a,
+		kind: e.Literal("entered"),
+		enteredGeneration: t
+	}).pipe(e.check(e.makeFilter((e) => e.enteredGeneration !== e.originalGeneration && e.dispatchAttempts > 0, { message: "Restart entry requires a dispatched command and a new generation" })))
+]), s = e.Union([o, e.Struct({
+	...r.fields,
+	kind: e.Literal("not-reserved"),
+	reason: e.Literals(["admission", "journal"])
+})]);
+//#endregion
+export { i as WorkflowRestartCommandSchema, o as WorkflowRestartObservationSchema, s as WorkflowRestartResultSchema, n as WorkflowRestartSelectionSchema, r as WorkflowRestartTargetSchema };

package/dist/workflowRetry.js

@@ -0,0 +1,44 @@
+import { WorkflowStartTerminalOutcomeSchema as e } from "./workflowStartOutcome.js";
+import { Schema as t } from "effect";
+//#region src/workflowRetry.ts
+var n = t.NonEmptyString.pipe(t.check(t.makeFilter((e) => e.trim().length > 0, { message: "A workflow retry identity must not be blank" }))), r = t.Struct({
+	runId: n,
+	requestId: n
+}), i = t.Struct({
+	...r.fields,
+	payloadOverride: t.optional(t.Unknown)
+}), a = {
+	requestId: t.NonEmptyString,
+	originalRunId: t.NonEmptyString,
+	originalExecutionId: t.NonEmptyString,
+	workflowName: t.NonEmptyString
+}, o = t.Union([
+	t.Struct({
+		...a,
+		kind: t.Literal("queued"),
+		nextAttemptAt: t.NullOr(t.Number)
+	}),
+	t.Struct({
+		...a,
+		kind: t.Literal("accepted"),
+		executionId: t.NonEmptyString
+	}).pipe(t.check(t.makeFilter((e) => e.executionId !== e.originalExecutionId, { message: "A retry cannot accept its original execution identity" }))),
+	t.Struct({
+		...a,
+		kind: t.Literal("unconfirmed"),
+		automaticRetryStopped: t.Boolean,
+		nextAttemptAt: t.NullOr(t.Number)
+	}).pipe(t.check(t.makeFilter((e) => !e.automaticRetryStopped || e.nextAttemptAt === null, { message: "Stopped automatic retries cannot have a next attempt" }))),
+	t.Struct({
+		...a,
+		kind: t.Literal("not-started"),
+		outcome: e
+	}),
+	t.Struct({
+		...a,
+		kind: t.Literal("rejected"),
+		failureId: t.NonEmptyString
+	})
+]);
+//#endregion
+export { i as WorkflowRetryCommandSchema, o as WorkflowRetryObservationSchema, r as WorkflowRetryTargetSchema };

package/dist/workflowStartOutcome.js

@@ -0,0 +1,30 @@
+import { Schema as e } from "effect";
+//#region src/workflowStartOutcome.ts
+var t = e.Union([
+	e.Struct({
+		kind: e.Literal("dropped"),
+		at: e.Number,
+		retryAfterMs: e.Number
+	}),
+	e.Struct({
+		kind: e.Literal("skipped"),
+		at: e.Number,
+		executionId: e.String,
+		runId: e.String
+	}),
+	e.Struct({
+		kind: e.Literal("superseded"),
+		at: e.Number
+	}),
+	e.Struct({
+		kind: e.Literal("cancelled"),
+		at: e.Number
+	}),
+	e.Struct({
+		kind: e.Literal("abandoned"),
+		at: e.Number,
+		failureId: e.NonEmptyString
+	})
+]);
+//#endregion
+export { t as WorkflowStartTerminalOutcomeSchema };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltro/protocol",
-  "version": "0.85.0",
+  "version": "0.87.0",
   "description": "The Voltro wire + plugin contract — defineQuery/Mutation/Action/Stream, definePlugin, sessions / JWT / API-keys, and the RPC protocol.",
   "keywords": [
     "voltro",
@@ -63,8 +63,10 @@
     "node": ">=24.0.0"
   },
   "dependencies": {
-    "@voltro/database": "0.85.0",
-    "@voltro/logger": "0.85.0",
+    "@voltro/database": "0.87.0",
+    "@voltro/kv": "0.87.0",
+    "@voltro/logger": "0.87.0",
+    "@voltro/shared": "0.87.0",
     "jose": "^6.2.12"
   },
   "peerDependencies": {