@flowmarkdev/core 0.0.0-stage → 0.1.0-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Martin Persson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,9 @@
-# Temporary Holding Version
+# @flowmarkdev/core
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Shared workflow event contracts for Flowmark. Application code should depend on
+[`@flowmarkdev/node`](https://www.npmjs.com/package/@flowmarkdev/node) instead of
+importing this package directly.
+
+This package is published so the Node SDK can resolve a normal registry
+dependency. The schemas and types here define the telemetry envelope that the
+API accepts.

package/dist/errors.d.ts

@@ -0,0 +1,10 @@
+import { Schema } from "effect";
+export declare const WorkflowFailureSchema: Schema.Struct<{
+    code: Schema.filter<Schema.filter<typeof Schema.String>>;
+    message: Schema.optional<Schema.filter<typeof Schema.String>>;
+    retryable: Schema.optional<typeof Schema.Boolean>;
+}>;
+/** Structured details for a terminal `failed` event. */
+export type WorkflowFailure = Schema.Schema.Type<typeof WorkflowFailureSchema>;
+/** A bounded operation failure code and optional diagnostic detail. */
+export type WorkflowOperationFailure = WorkflowFailure;

package/dist/errors.js

@@ -0,0 +1,6 @@
+import { Schema } from "effect";
+export const WorkflowFailureSchema = Schema.Struct({
+    code: Schema.String.pipe(Schema.minLength(1), Schema.maxLength(128)),
+    message: Schema.optional(Schema.String.pipe(Schema.maxLength(2048))),
+    retryable: Schema.optional(Schema.Boolean),
+});

package/dist/events.d.ts

@@ -0,0 +1,344 @@
+import { Effect, Schema } from "effect";
+export declare const WorkflowEventSchema: Schema.Union<[Schema.filter<Schema.Struct<{
+    type: Schema.Literal<["started"]>;
+    workflow: typeof Schema.String;
+    runId: typeof Schema.String;
+    timestamp: typeof Schema.String;
+    properties: Schema.optional<Schema.refine<{
+        readonly [x: string]: unknown;
+    } & import("./json.js").WorkflowProperties, Schema.Schema<unknown, {
+        readonly [x: string]: unknown;
+    }, never>>>;
+    environment: Schema.optional<Schema.filter<typeof Schema.String>>;
+    release: Schema.optional<Schema.filter<typeof Schema.String>>;
+    correlationId: Schema.optional<Schema.filter<Schema.filter<typeof Schema.String>>>;
+    parentRunId: Schema.optional<Schema.filter<Schema.filter<typeof Schema.String>>>;
+}>>, Schema.Struct<{
+    type: Schema.Literal<["step"]>;
+    workflow: typeof Schema.String;
+    runId: typeof Schema.String;
+    step: typeof Schema.String;
+    timestamp: typeof Schema.String;
+    properties: Schema.optional<Schema.refine<{
+        readonly [x: string]: unknown;
+    } & import("./json.js").WorkflowProperties, Schema.Schema<unknown, {
+        readonly [x: string]: unknown;
+    }, never>>>;
+}>, Schema.Struct<{
+    type: Schema.Literal<["properties"]>;
+    workflow: typeof Schema.String;
+    runId: typeof Schema.String;
+    timestamp: typeof Schema.String;
+    properties: Schema.refine<{
+        readonly [x: string]: unknown;
+    } & import("./json.js").WorkflowProperties, Schema.Schema<unknown, {
+        readonly [x: string]: unknown;
+    }, never>>;
+}>, Schema.Struct<{
+    type: Schema.Literal<["completed"]>;
+    workflow: typeof Schema.String;
+    runId: typeof Schema.String;
+    timestamp: typeof Schema.String;
+    result: Schema.optional<Schema.refine<{
+        readonly [x: string]: unknown;
+    } & import("./json.js").WorkflowProperties, Schema.Schema<unknown, {
+        readonly [x: string]: unknown;
+    }, never>>>;
+}>, Schema.Struct<{
+    type: Schema.Literal<["failed"]>;
+    workflow: typeof Schema.String;
+    runId: typeof Schema.String;
+    timestamp: typeof Schema.String;
+    reason: Schema.optional<Schema.filter<typeof Schema.String>>;
+    failure: Schema.optional<Schema.Struct<{
+        code: Schema.filter<Schema.filter<typeof Schema.String>>;
+        message: Schema.optional<Schema.filter<typeof Schema.String>>;
+        retryable: Schema.optional<typeof Schema.Boolean>;
+    }>>;
+    result: Schema.optional<Schema.refine<{
+        readonly [x: string]: unknown;
+    } & import("./json.js").WorkflowProperties, Schema.Schema<unknown, {
+        readonly [x: string]: unknown;
+    }, never>>>;
+}>, Schema.Struct<{
+    type: Schema.Literal<["error"]>;
+    workflow: typeof Schema.String;
+    runId: typeof Schema.String;
+    timestamp: typeof Schema.String;
+    error: Schema.Struct<{
+        code: Schema.filter<Schema.filter<typeof Schema.String>>;
+        message: Schema.optional<Schema.filter<typeof Schema.String>>;
+        retryable: Schema.optional<typeof Schema.Boolean>;
+        handled: typeof Schema.Boolean;
+    }>;
+}>, Schema.Struct<{
+    type: Schema.Literal<["operation_started"]>;
+    workflow: typeof Schema.String;
+    runId: typeof Schema.String;
+    timestamp: typeof Schema.String;
+    operationId: typeof Schema.UUID;
+    operationName: Schema.filter<Schema.filter<Schema.filter<typeof Schema.String>>>;
+    properties: Schema.optional<Schema.refine<{
+        readonly [x: string]: unknown;
+    } & import("./json.js").WorkflowProperties, Schema.Schema<unknown, {
+        readonly [x: string]: unknown;
+    }, never>>>;
+}>, Schema.Struct<{
+    type: Schema.Literal<["operation_completed"]>;
+    workflow: typeof Schema.String;
+    runId: typeof Schema.String;
+    timestamp: typeof Schema.String;
+    operationId: typeof Schema.UUID;
+    operationName: Schema.filter<Schema.filter<Schema.filter<typeof Schema.String>>>;
+    durationMs: Schema.filter<typeof Schema.Number>;
+}>, Schema.Struct<{
+    type: Schema.Literal<["operation_failed"]>;
+    workflow: typeof Schema.String;
+    runId: typeof Schema.String;
+    timestamp: typeof Schema.String;
+    operationId: typeof Schema.UUID;
+    operationName: Schema.filter<Schema.filter<Schema.filter<typeof Schema.String>>>;
+    durationMs: Schema.filter<typeof Schema.Number>;
+    failure: Schema.Struct<{
+        code: Schema.filter<Schema.filter<typeof Schema.String>>;
+        message: Schema.optional<Schema.filter<typeof Schema.String>>;
+        retryable: Schema.optional<typeof Schema.Boolean>;
+    }>;
+}>, Schema.filter<Schema.Struct<{
+    completed: Schema.filter<Schema.filter<typeof Schema.Number>>;
+    total: Schema.optional<Schema.filter<Schema.filter<typeof Schema.Number>>>;
+    unit: Schema.optional<Schema.filter<Schema.filter<typeof Schema.String>>>;
+    type: Schema.Literal<["progress"]>;
+    workflow: typeof Schema.String;
+    runId: typeof Schema.String;
+    timestamp: typeof Schema.String;
+}>>]>;
+export type WorkflowEvent = Schema.Schema.Type<typeof WorkflowEventSchema>;
+export declare const EventEnvelopeSchema: Schema.Struct<{
+    eventId: typeof Schema.UUID;
+    event: Schema.filter<Schema.Union<[Schema.filter<Schema.Struct<{
+        type: Schema.Literal<["started"]>;
+        workflow: typeof Schema.String;
+        runId: typeof Schema.String;
+        timestamp: typeof Schema.String;
+        properties: Schema.optional<Schema.refine<{
+            readonly [x: string]: unknown;
+        } & import("./json.js").WorkflowProperties, Schema.Schema<unknown, {
+            readonly [x: string]: unknown;
+        }, never>>>;
+        environment: Schema.optional<Schema.filter<typeof Schema.String>>;
+        release: Schema.optional<Schema.filter<typeof Schema.String>>;
+        correlationId: Schema.optional<Schema.filter<Schema.filter<typeof Schema.String>>>;
+        parentRunId: Schema.optional<Schema.filter<Schema.filter<typeof Schema.String>>>;
+    }>>, Schema.Struct<{
+        type: Schema.Literal<["step"]>;
+        workflow: typeof Schema.String;
+        runId: typeof Schema.String;
+        step: typeof Schema.String;
+        timestamp: typeof Schema.String;
+        properties: Schema.optional<Schema.refine<{
+            readonly [x: string]: unknown;
+        } & import("./json.js").WorkflowProperties, Schema.Schema<unknown, {
+            readonly [x: string]: unknown;
+        }, never>>>;
+    }>, Schema.Struct<{
+        type: Schema.Literal<["properties"]>;
+        workflow: typeof Schema.String;
+        runId: typeof Schema.String;
+        timestamp: typeof Schema.String;
+        properties: Schema.refine<{
+            readonly [x: string]: unknown;
+        } & import("./json.js").WorkflowProperties, Schema.Schema<unknown, {
+            readonly [x: string]: unknown;
+        }, never>>;
+    }>, Schema.Struct<{
+        type: Schema.Literal<["completed"]>;
+        workflow: typeof Schema.String;
+        runId: typeof Schema.String;
+        timestamp: typeof Schema.String;
+        result: Schema.optional<Schema.refine<{
+            readonly [x: string]: unknown;
+        } & import("./json.js").WorkflowProperties, Schema.Schema<unknown, {
+            readonly [x: string]: unknown;
+        }, never>>>;
+    }>, Schema.Struct<{
+        type: Schema.Literal<["failed"]>;
+        workflow: typeof Schema.String;
+        runId: typeof Schema.String;
+        timestamp: typeof Schema.String;
+        reason: Schema.optional<Schema.filter<typeof Schema.String>>;
+        failure: Schema.optional<Schema.Struct<{
+            code: Schema.filter<Schema.filter<typeof Schema.String>>;
+            message: Schema.optional<Schema.filter<typeof Schema.String>>;
+            retryable: Schema.optional<typeof Schema.Boolean>;
+        }>>;
+        result: Schema.optional<Schema.refine<{
+            readonly [x: string]: unknown;
+        } & import("./json.js").WorkflowProperties, Schema.Schema<unknown, {
+            readonly [x: string]: unknown;
+        }, never>>>;
+    }>, Schema.Struct<{
+        type: Schema.Literal<["error"]>;
+        workflow: typeof Schema.String;
+        runId: typeof Schema.String;
+        timestamp: typeof Schema.String;
+        error: Schema.Struct<{
+            code: Schema.filter<Schema.filter<typeof Schema.String>>;
+            message: Schema.optional<Schema.filter<typeof Schema.String>>;
+            retryable: Schema.optional<typeof Schema.Boolean>;
+            handled: typeof Schema.Boolean;
+        }>;
+    }>, Schema.Struct<{
+        type: Schema.Literal<["operation_started"]>;
+        workflow: typeof Schema.String;
+        runId: typeof Schema.String;
+        timestamp: typeof Schema.String;
+        operationId: typeof Schema.UUID;
+        operationName: Schema.filter<Schema.filter<Schema.filter<typeof Schema.String>>>;
+        properties: Schema.optional<Schema.refine<{
+            readonly [x: string]: unknown;
+        } & import("./json.js").WorkflowProperties, Schema.Schema<unknown, {
+            readonly [x: string]: unknown;
+        }, never>>>;
+    }>, Schema.Struct<{
+        type: Schema.Literal<["operation_completed"]>;
+        workflow: typeof Schema.String;
+        runId: typeof Schema.String;
+        timestamp: typeof Schema.String;
+        operationId: typeof Schema.UUID;
+        operationName: Schema.filter<Schema.filter<Schema.filter<typeof Schema.String>>>;
+        durationMs: Schema.filter<typeof Schema.Number>;
+    }>, Schema.Struct<{
+        type: Schema.Literal<["operation_failed"]>;
+        workflow: typeof Schema.String;
+        runId: typeof Schema.String;
+        timestamp: typeof Schema.String;
+        operationId: typeof Schema.UUID;
+        operationName: Schema.filter<Schema.filter<Schema.filter<typeof Schema.String>>>;
+        durationMs: Schema.filter<typeof Schema.Number>;
+        failure: Schema.Struct<{
+            code: Schema.filter<Schema.filter<typeof Schema.String>>;
+            message: Schema.optional<Schema.filter<typeof Schema.String>>;
+            retryable: Schema.optional<typeof Schema.Boolean>;
+        }>;
+    }>, Schema.filter<Schema.Struct<{
+        completed: Schema.filter<Schema.filter<typeof Schema.Number>>;
+        total: Schema.optional<Schema.filter<Schema.filter<typeof Schema.Number>>>;
+        unit: Schema.optional<Schema.filter<Schema.filter<typeof Schema.String>>>;
+        type: Schema.Literal<["progress"]>;
+        workflow: typeof Schema.String;
+        runId: typeof Schema.String;
+        timestamp: typeof Schema.String;
+    }>>]>>;
+}>;
+declare const WorkflowEventValidationError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "WorkflowEventValidationError";
+} & Readonly<A>;
+export declare class WorkflowEventValidationError extends WorkflowEventValidationError_base<{
+    readonly input: unknown;
+    readonly cause: unknown;
+}> {
+}
+export declare const decodeWorkflowEvent: (input: unknown) => Effect.Effect<{
+    readonly type: "started";
+    readonly workflow: string;
+    readonly runId: string;
+    readonly timestamp: string;
+    readonly properties?: ({
+        readonly [x: string]: unknown;
+    } & import("./json.js").WorkflowProperties) | undefined;
+    readonly environment?: string | undefined;
+    readonly release?: string | undefined;
+    readonly correlationId?: string | undefined;
+    readonly parentRunId?: string | undefined;
+} | {
+    readonly completed: number;
+    readonly total?: number | undefined;
+    readonly unit?: string | undefined;
+    readonly type: "progress";
+    readonly workflow: string;
+    readonly runId: string;
+    readonly timestamp: string;
+} | {
+    readonly type: "step";
+    readonly workflow: string;
+    readonly runId: string;
+    readonly timestamp: string;
+    readonly properties?: ({
+        readonly [x: string]: unknown;
+    } & import("./json.js").WorkflowProperties) | undefined;
+    readonly step: string;
+} | {
+    readonly type: "properties";
+    readonly workflow: string;
+    readonly runId: string;
+    readonly timestamp: string;
+    readonly properties: {
+        readonly [x: string]: unknown;
+    } & import("./json.js").WorkflowProperties;
+} | {
+    readonly type: "completed";
+    readonly workflow: string;
+    readonly runId: string;
+    readonly timestamp: string;
+    readonly result?: ({
+        readonly [x: string]: unknown;
+    } & import("./json.js").WorkflowProperties) | undefined;
+} | {
+    readonly type: "failed";
+    readonly workflow: string;
+    readonly runId: string;
+    readonly timestamp: string;
+    readonly result?: ({
+        readonly [x: string]: unknown;
+    } & import("./json.js").WorkflowProperties) | undefined;
+    readonly reason?: string | undefined;
+    readonly failure?: {
+        readonly code: string;
+        readonly message?: string | undefined;
+        readonly retryable?: boolean | undefined;
+    } | undefined;
+} | {
+    readonly type: "error";
+    readonly workflow: string;
+    readonly runId: string;
+    readonly timestamp: string;
+    readonly error: {
+        readonly code: string;
+        readonly message?: string | undefined;
+        readonly retryable?: boolean | undefined;
+        readonly handled: boolean;
+    };
+} | {
+    readonly type: "operation_started";
+    readonly workflow: string;
+    readonly runId: string;
+    readonly timestamp: string;
+    readonly properties?: ({
+        readonly [x: string]: unknown;
+    } & import("./json.js").WorkflowProperties) | undefined;
+    readonly operationId: string;
+    readonly operationName: string;
+} | {
+    readonly type: "operation_completed";
+    readonly workflow: string;
+    readonly runId: string;
+    readonly timestamp: string;
+    readonly operationId: string;
+    readonly operationName: string;
+    readonly durationMs: number;
+} | {
+    readonly type: "operation_failed";
+    readonly workflow: string;
+    readonly runId: string;
+    readonly timestamp: string;
+    readonly failure: {
+        readonly code: string;
+        readonly message?: string | undefined;
+        readonly retryable?: boolean | undefined;
+    };
+    readonly operationId: string;
+    readonly operationName: string;
+    readonly durationMs: number;
+}, WorkflowEventValidationError, never>;
+export {};

package/dist/events.js

@@ -0,0 +1,108 @@
+import { Data, Effect, Match, Schema } from "effect";
+import { IngestionIdentifierSchema, WorkflowCorrelationIdSchema, WorkflowLinkIdSchema, WorkflowNameSchema, WorkflowRunIdSchema, WorkflowStepNameSchema, } from "./identifiers.js";
+import { WorkflowPropertiesSchema, WorkflowResultSchema } from "./json.js";
+import { WorkflowErrorSchema, WorkflowProgressFields } from "./telemetry.js";
+import { WorkflowFailureSchema } from "./errors.js";
+const StartedEventSchema = Schema.Struct({
+    type: Schema.Literal("started"),
+    workflow: WorkflowNameSchema,
+    runId: WorkflowRunIdSchema,
+    timestamp: Schema.String,
+    properties: Schema.optional(WorkflowPropertiesSchema),
+    environment: Schema.optional(Schema.String.pipe(Schema.maxLength(128))),
+    release: Schema.optional(Schema.String.pipe(Schema.maxLength(256))),
+    correlationId: Schema.optional(WorkflowCorrelationIdSchema),
+    parentRunId: Schema.optional(WorkflowLinkIdSchema),
+}).pipe(Schema.filter(({ runId, parentRunId }) => parentRunId === undefined || parentRunId !== runId));
+const StepEventSchema = Schema.Struct({
+    type: Schema.Literal("step"),
+    workflow: WorkflowNameSchema,
+    runId: WorkflowRunIdSchema,
+    step: WorkflowStepNameSchema,
+    timestamp: Schema.String,
+    properties: Schema.optional(WorkflowPropertiesSchema),
+});
+const PropertiesEventSchema = Schema.Struct({
+    type: Schema.Literal("properties"),
+    workflow: WorkflowNameSchema,
+    runId: WorkflowRunIdSchema,
+    timestamp: Schema.String,
+    properties: WorkflowPropertiesSchema,
+});
+const CompletedEventSchema = Schema.Struct({
+    type: Schema.Literal("completed"),
+    workflow: WorkflowNameSchema,
+    runId: WorkflowRunIdSchema,
+    timestamp: Schema.String,
+    result: Schema.optional(WorkflowResultSchema),
+});
+const FailedEventSchema = Schema.Struct({
+    type: Schema.Literal("failed"),
+    workflow: WorkflowNameSchema,
+    runId: WorkflowRunIdSchema,
+    timestamp: Schema.String,
+    reason: Schema.optional(Schema.String.pipe(Schema.maxLength(2048))),
+    failure: Schema.optional(WorkflowFailureSchema),
+    result: Schema.optional(WorkflowResultSchema),
+});
+const ErrorEventSchema = Schema.Struct({
+    type: Schema.Literal("error"),
+    workflow: WorkflowNameSchema,
+    runId: WorkflowRunIdSchema,
+    timestamp: Schema.String,
+    error: WorkflowErrorSchema,
+});
+const OperationDurationSchema = Schema.Number.pipe(Schema.filter((duration) => Number.isFinite(duration) && duration >= 0));
+const OperationNameSchema = Schema.String.pipe(Schema.minLength(1), Schema.maxLength(200), Schema.filter((value) => value.trim().length > 0));
+const OperationStartedEventSchema = Schema.Struct({
+    type: Schema.Literal("operation_started"),
+    workflow: WorkflowNameSchema,
+    runId: WorkflowRunIdSchema,
+    timestamp: Schema.String,
+    operationId: Schema.UUID,
+    operationName: OperationNameSchema,
+    properties: Schema.optional(WorkflowPropertiesSchema),
+});
+const OperationCompletedEventSchema = Schema.Struct({
+    type: Schema.Literal("operation_completed"),
+    workflow: WorkflowNameSchema,
+    runId: WorkflowRunIdSchema,
+    timestamp: Schema.String,
+    operationId: Schema.UUID,
+    operationName: OperationNameSchema,
+    durationMs: OperationDurationSchema,
+});
+const OperationFailedEventSchema = Schema.Struct({
+    type: Schema.Literal("operation_failed"),
+    workflow: WorkflowNameSchema,
+    runId: WorkflowRunIdSchema,
+    timestamp: Schema.String,
+    operationId: Schema.UUID,
+    operationName: OperationNameSchema,
+    durationMs: OperationDurationSchema,
+    failure: WorkflowFailureSchema,
+});
+const ProgressEventSchema = Schema.Struct({
+    type: Schema.Literal("progress"),
+    workflow: WorkflowNameSchema,
+    runId: WorkflowRunIdSchema,
+    timestamp: Schema.String,
+    ...WorkflowProgressFields,
+}).pipe(Schema.filter(({ completed, total }) => total === undefined || completed <= total));
+export const WorkflowEventSchema = Schema.Union(StartedEventSchema, StepEventSchema, PropertiesEventSchema, CompletedEventSchema, FailedEventSchema, ErrorEventSchema, OperationStartedEventSchema, OperationCompletedEventSchema, OperationFailedEventSchema, ProgressEventSchema);
+export const EventEnvelopeSchema = Schema.Struct({
+    eventId: Schema.UUID,
+    event: WorkflowEventSchema.pipe(Schema.filter((event) => Number.isFinite(Date.parse(event.timestamp)) &&
+        Schema.is(IngestionIdentifierSchema)(event.workflow) &&
+        Schema.is(IngestionIdentifierSchema)(event.runId) &&
+        (event.type !== "started" ||
+            ((event.correlationId === undefined ||
+                Schema.is(WorkflowCorrelationIdSchema)(event.correlationId)) &&
+                (event.parentRunId === undefined ||
+                    (Schema.is(WorkflowLinkIdSchema)(event.parentRunId) &&
+                        event.parentRunId !== event.runId)))) &&
+        Match.value(event).pipe(Match.when({ type: "step" }, ({ step }) => Schema.is(IngestionIdentifierSchema)(step)), Match.when({ type: "operation_started" }, ({ operationName }) => Schema.is(IngestionIdentifierSchema)(operationName)), Match.when({ type: "operation_completed" }, ({ operationName }) => Schema.is(IngestionIdentifierSchema)(operationName)), Match.when({ type: "operation_failed" }, ({ operationName }) => Schema.is(IngestionIdentifierSchema)(operationName)), Match.orElse(() => true)))),
+});
+export class WorkflowEventValidationError extends Data.TaggedError("WorkflowEventValidationError") {
+}
+export const decodeWorkflowEvent = Effect.fn("Flowmark.decodeWorkflowEvent")((input) => Schema.decodeUnknown(WorkflowEventSchema)(input).pipe(Effect.mapError((cause) => new WorkflowEventValidationError({ input, cause }))));

package/dist/identifiers.d.ts

@@ -0,0 +1,12 @@
+import { Schema } from "effect";
+export declare const WorkflowNameSchema: typeof Schema.String;
+export declare const WorkflowRunIdSchema: typeof Schema.String;
+export declare const WorkflowStepNameSchema: typeof Schema.String;
+export type WorkflowName = Schema.Schema.Type<typeof WorkflowNameSchema>;
+export type WorkflowRunId = Schema.Schema.Type<typeof WorkflowRunIdSchema>;
+export type WorkflowStepName = Schema.Schema.Type<typeof WorkflowStepNameSchema>;
+export declare const WorkflowLinkIdSchema: Schema.filter<Schema.filter<typeof Schema.String>>;
+/** Optional explicit grouping identifier; do not use secrets or personal data. */
+export declare const WorkflowCorrelationIdSchema: Schema.filter<Schema.filter<typeof Schema.String>>;
+export type WorkflowCorrelationId = Schema.Schema.Type<typeof WorkflowCorrelationIdSchema>;
+export declare const IngestionIdentifierSchema: Schema.filter<Schema.filter<typeof Schema.String>>;

package/dist/identifiers.js

@@ -0,0 +1,8 @@
+import { Schema } from "effect";
+export const WorkflowNameSchema = Schema.String;
+export const WorkflowRunIdSchema = Schema.String;
+export const WorkflowStepNameSchema = Schema.String;
+export const WorkflowLinkIdSchema = Schema.String.pipe(Schema.maxLength(200), Schema.filter((value) => value.trim().length > 0));
+/** Optional explicit grouping identifier; do not use secrets or personal data. */
+export const WorkflowCorrelationIdSchema = Schema.String.pipe(Schema.maxLength(128), Schema.filter((value) => value.trim().length > 0));
+export const IngestionIdentifierSchema = Schema.String.pipe(Schema.maxLength(200), Schema.filter((value) => value.trim().length > 0));

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export { WorkflowCorrelationIdSchema, WorkflowNameSchema, WorkflowRunIdSchema, WorkflowStepNameSchema, } from "./identifiers.js";
+export type { WorkflowCorrelationId, WorkflowName, WorkflowRunId, WorkflowStepName, } from "./identifiers.js";
+export { WORKFLOW_JSON_LIMITS, WorkflowPropertiesSchema, WorkflowResultSchema, } from "./json.js";
+export type { JsonValue, WorkflowProperties, WorkflowResult } from "./json.js";
+export { WorkflowErrorSchema, WorkflowProgressSchema } from "./telemetry.js";
+export type { WorkflowError, WorkflowProgress } from "./telemetry.js";
+export { WorkflowFailureSchema } from "./errors.js";
+export type { WorkflowFailure, WorkflowOperationFailure } from "./errors.js";
+export { EventEnvelopeSchema, WorkflowEventSchema, WorkflowEventValidationError, decodeWorkflowEvent, } from "./events.js";
+export type { WorkflowEvent } from "./events.js";

package/dist/index.js

@@ -0,0 +1,5 @@
+export { WorkflowCorrelationIdSchema, WorkflowNameSchema, WorkflowRunIdSchema, WorkflowStepNameSchema, } from "./identifiers.js";
+export { WORKFLOW_JSON_LIMITS, WorkflowPropertiesSchema, WorkflowResultSchema, } from "./json.js";
+export { WorkflowErrorSchema, WorkflowProgressSchema } from "./telemetry.js";
+export { WorkflowFailureSchema } from "./errors.js";
+export { EventEnvelopeSchema, WorkflowEventSchema, WorkflowEventValidationError, decodeWorkflowEvent, } from "./events.js";

package/dist/json.d.ts

@@ -0,0 +1,31 @@
+import { Schema } from "effect";
+/**
+ * Limits applied to properties and results in both the SDK and ingestion API.
+ * Nested values allow at most five levels, 128 keys total, 128 characters per
+ * key, 2,048 characters per string, and 16 KiB of UTF-8 JSON per object.
+ */
+export declare const WORKFLOW_JSON_LIMITS: {
+    readonly maxDepth: 5;
+    readonly maxKeys: 128;
+    readonly maxKeyLength: 128;
+    readonly maxStringLength: 2048;
+    readonly maxBytes: number;
+};
+/** Recursive JSON value admitted by the bounded workflow context/result schema. */
+export type JsonValue = null | boolean | number | string | JsonValue[] | {
+    readonly [key: string]: JsonValue;
+};
+/** Bounded JSON-safe context object accepted on starts, steps, and amendments. */
+export type WorkflowProperties = Record<string, JsonValue>;
+/** Bounded JSON-safe object recorded when a run completes. */
+export type WorkflowResult = Record<string, JsonValue>;
+export declare const WorkflowPropertiesSchema: Schema.refine<{
+    readonly [x: string]: unknown;
+} & WorkflowProperties, Schema.Schema<unknown, {
+    readonly [x: string]: unknown;
+}, never>>;
+export declare const WorkflowResultSchema: Schema.refine<{
+    readonly [x: string]: unknown;
+} & WorkflowProperties, Schema.Schema<unknown, {
+    readonly [x: string]: unknown;
+}, never>>;

package/dist/json.js

@@ -0,0 +1,80 @@
+import { Schema } from "effect";
+/**
+ * Limits applied to properties and results in both the SDK and ingestion API.
+ * Nested values allow at most five levels, 128 keys total, 128 characters per
+ * key, 2,048 characters per string, and 16 KiB of UTF-8 JSON per object.
+ */
+export const WORKFLOW_JSON_LIMITS = {
+    maxDepth: 5,
+    maxKeys: 128,
+    maxKeyLength: 128,
+    maxStringLength: 2048,
+    maxBytes: 16 * 1024,
+};
+const isBoundedJsonObject = (input) => {
+    if (input === null || typeof input !== "object" || Array.isArray(input)) {
+        return false;
+    }
+    let keys = 0;
+    const ancestors = new Set();
+    try {
+        const visit = (value, depth) => {
+            if (depth > WORKFLOW_JSON_LIMITS.maxDepth) {
+                return false;
+            }
+            if (value === null ||
+                typeof value === "boolean" ||
+                (typeof value === "number" && Number.isFinite(value))) {
+                return true;
+            }
+            if (typeof value === "string") {
+                return value.length <= WORKFLOW_JSON_LIMITS.maxStringLength;
+            }
+            if (typeof value !== "object") {
+                return false;
+            }
+            if (ancestors.has(value)) {
+                return false;
+            }
+            if (!Array.isArray(value) &&
+                Object.getPrototypeOf(value) !== Object.prototype &&
+                Object.getPrototypeOf(value) !== null) {
+                return false;
+            }
+            ancestors.add(value);
+            let valid = true;
+            if (Array.isArray(value)) {
+                for (let index = 0; index < value.length; index += 1) {
+                    if (!(index in value) || !visit(value[index], depth + 1)) {
+                        valid = false;
+                        break;
+                    }
+                }
+            }
+            else {
+                const entries = Object.entries(value);
+                keys += entries.length;
+                valid =
+                    keys <= WORKFLOW_JSON_LIMITS.maxKeys &&
+                        entries.every(([key, item]) => key.length <= WORKFLOW_JSON_LIMITS.maxKeyLength &&
+                            visit(item, depth + 1));
+            }
+            ancestors.delete(value);
+            return valid;
+        };
+        if (!visit(input, 0)) {
+            return false;
+        }
+        return (new TextEncoder().encode(JSON.stringify(input)).byteLength <=
+            WORKFLOW_JSON_LIMITS.maxBytes);
+    }
+    catch {
+        return false;
+    }
+};
+const WorkflowJsonObjectSchema = Schema.Record({
+    key: Schema.String,
+    value: Schema.Unknown,
+}).pipe(Schema.filter(isBoundedJsonObject));
+export const WorkflowPropertiesSchema = WorkflowJsonObjectSchema;
+export const WorkflowResultSchema = WorkflowJsonObjectSchema;

package/dist/telemetry.d.ts

@@ -0,0 +1,21 @@
+import { Schema } from "effect";
+export declare const WorkflowErrorSchema: Schema.Struct<{
+    code: Schema.filter<Schema.filter<typeof Schema.String>>;
+    message: Schema.optional<Schema.filter<typeof Schema.String>>;
+    retryable: Schema.optional<typeof Schema.Boolean>;
+    handled: typeof Schema.Boolean;
+}>;
+export declare const WorkflowProgressFields: {
+    completed: Schema.filter<Schema.filter<typeof Schema.Number>>;
+    total: Schema.optional<Schema.filter<Schema.filter<typeof Schema.Number>>>;
+    unit: Schema.optional<Schema.filter<Schema.filter<typeof Schema.String>>>;
+};
+export declare const WorkflowProgressSchema: Schema.filter<Schema.Struct<{
+    completed: Schema.filter<Schema.filter<typeof Schema.Number>>;
+    total: Schema.optional<Schema.filter<Schema.filter<typeof Schema.Number>>>;
+    unit: Schema.optional<Schema.filter<Schema.filter<typeof Schema.String>>>;
+}>>;
+/** A recoverable error event; `handled` records whether application code handled it. */
+export type WorkflowError = Schema.Schema.Type<typeof WorkflowErrorSchema>;
+/** Absolute progress snapshot for a workflow run. */
+export type WorkflowProgress = Schema.Schema.Type<typeof WorkflowProgressSchema>;

package/dist/telemetry.js

@@ -0,0 +1,13 @@
+import { Schema } from "effect";
+export const WorkflowErrorSchema = Schema.Struct({
+    code: Schema.String.pipe(Schema.minLength(1), Schema.maxLength(128)),
+    message: Schema.optional(Schema.String.pipe(Schema.maxLength(2048))),
+    retryable: Schema.optional(Schema.Boolean),
+    handled: Schema.Boolean,
+});
+export const WorkflowProgressFields = {
+    completed: Schema.Number.pipe(Schema.filter(Number.isSafeInteger), Schema.nonNegative()),
+    total: Schema.optional(Schema.Number.pipe(Schema.filter(Number.isSafeInteger), Schema.nonNegative())),
+    unit: Schema.optional(Schema.String.pipe(Schema.minLength(1), Schema.maxLength(64))),
+};
+export const WorkflowProgressSchema = Schema.Struct(WorkflowProgressFields).pipe(Schema.filter(({ completed, total }) => total === undefined || completed <= total));

package/package.json

@@ -1,6 +1,50 @@
 {
   "name": "@flowmarkdev/core",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0-alpha.0",
+  "description": "Shared workflow event contracts for Flowmark",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Mumma6/flowmark.git",
+    "directory": "packages/core"
+  },
+  "homepage": "https://flowmark.dev",
+  "bugs": {
+    "url": "https://github.com/Mumma6/flowmark/issues"
+  },
+  "engines": {
+    "node": ">=20.19"
+  },
+  "scripts": {
+    "dev": "tsc -p tsconfig.build.json --watch --preserveWatchOutput",
+    "build": "tsc -p tsconfig.build.json",
+    "lint": "eslint src test",
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.json"
+  },
+  "dependencies": {
+    "effect": "^3.22.4"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.2",
+    "vitest": "^3.2.4"
+  }
+}