@shapeshift-labs/frontier-workflow

v0.1.0

Published

22 days ago

Serializable durable workflow and process manifests for Frontier apps.

0High
0Medium
0Low

shapeshift-labs

frontier workflow durable process saga approval retry compensation

@shapeshift-labs/frontier-workflow

Serializable durable workflow and process manifests for Frontier apps.

frontier-workflow turns long-running business/process flows into data: steps, waits, approvals, timers, retries, expected patches, effects, compensation, records, timelines, and registry graph output. It is not a workflow server and it does not import policy, tools, effects, event-log, scheduler, trace, route, or view packages. Those systems attach through structural adapters.

Related Packages

The published Frontier package family is generated from one shared package catalog so READMEs stay in sync across packages:

@shapeshift-labs/frontier: Core JSON diff/apply, compact patch tuples, JSON Pointer, equality, clone, validation, Unicode helpers, and tiny dependency-free runtime budget/scheduler primitives.
@shapeshift-labs/frontier-query: Shared query-key, selector path, condition, entity identity, and table-shape primitives.
@shapeshift-labs/frontier-codec: Patch serialization, binary frames, canonical JSON, and patch-history codecs.
@shapeshift-labs/frontier-engine: Stateful planned diff engine, adaptive profiles, schema plans, and engine-level history helpers.
@shapeshift-labs/frontier-state: Patch-routed app-state subscriptions, owned commits, maintained views, and path mapping.
@shapeshift-labs/frontier-state-cache: Normalized query-result cache with entity/query watchers, persistence, change logs, optimistic layers, scheduled persistence, and mutation bridge.
@shapeshift-labs/frontier-state-cache-idb: IndexedDB persistence adapter for Frontier state-cache snapshots and durable change logs.
@shapeshift-labs/frontier-state-cache-file: Structured file persistence adapter for Frontier state-cache snapshots and change logs.
@shapeshift-labs/frontier-state-cache-sql: SQL persistence adapter for Frontier state-cache snapshots and change logs.
@shapeshift-labs/frontier-schema: JSON Schema validation, Frontier profile generation, CloudEvent envelopes, and query/table schema helpers.
@shapeshift-labs/frontier-migrations: Boundary-first data migrations, import normalization, plugin/API version mapping, versioned envelopes, graph diagnostics, patch path rewrites, dry-run reports, and current-shape rehydration.
@shapeshift-labs/frontier-event-log: Bounded event logs, replay cursors, consumer acknowledgements, keyed compaction, checkpoints, and Frontier patch event records.
@shapeshift-labs/frontier-inspect: Cross-package inspection/evidence bundles, registry graph snapshots, feature/resource impact reports, timeline/event normalization, redaction, JSONL import/export, and AI-readable app feature maps.
@shapeshift-labs/frontier-scheduler: Deterministic work scheduling, lanes, cancellation, backpressure, frame policies, replay snapshots, and work graphs.
@shapeshift-labs/frontier-logging: Opt-in structured logging, browser telemetry, scheduled sinks, file sinks, exporters, benchmark traces, and Frontier patch/update summaries.
@shapeshift-labs/frontier-mutation: Explicit mutation and selector plans compiled to Frontier patches or CRDT operations.
@shapeshift-labs/frontier-policy: Serializable policy and capability decisions for Frontier apps, effects, views, sync, routes, traces, and AI tools.
@shapeshift-labs/frontier-tools: Serializable app action/tool manifests for AI-operable Frontier apps, including availability, validation, dry-run plans, patch previews, effect/tool constraints, execution records, rollback links, and registry graph output.
@shapeshift-labs/frontier-triggers: Capability-gated event trigger registry, scoped event envelopes, listener/reaction rules, structured rejection, deterministic event-to-action scheduling, replay/provenance records, and registry graph output.
@shapeshift-labs/frontier-virtual: DOM-neutral virtualization, layout providers, range materialization, grids, spatial/frustum indexes, patch invalidation, camera anchors, and serializable layout state.
@shapeshift-labs/frontier-scene: Patch-native 2D/3D scene graph, transform propagation, bounds queries, virtual/culling adapters, spatial invalidation, and camera/frustum materialization.
@shapeshift-labs/frontier-pathfinding: Patch-native grid pathfinding, typed-array A*/Dijkstra search, flow fields, connected components, line-of-sight smoothing, dirty-cell invalidation, and scheduler-friendly path jobs.
@shapeshift-labs/frontier-lod: Patch-native level-of-detail and significance selection for rendering and computation workloads, compact typed hot paths, multi-observer selection, budget degradation, materialization frames, and scheduler work plans.
@shapeshift-labs/frontier-route: DOM-neutral app/game route resources, route and scene manifests, match/resolve/transition planning, dependency metadata, sessions, registry graph output, and impact queries.
@shapeshift-labs/frontier-trace: Serializable traces, spans, events, causal links, W3C trace context helpers, timeline/resource/path queries, critical-path analysis, registry graph output, JSONL/proof helpers, Chrome trace export, and redaction for app-wide feature observability.
@shapeshift-labs/frontier-manifest: Build/static feature manifests for owners, routes, actions, states, migrations, tests, source files, assets, resources, tasks, dependency metadata, registry graph output, feature maps, JSONL export, and impact queries.
@shapeshift-labs/frontier-view: Renderer-neutral view manifests, type defaults, validation frames, action bindings, visual channels, virtual/LOD hints, and data-to-representation mapping for Frontier apps.
@shapeshift-labs/frontier-dom: Patch-native DOM and host renderer bindings, manifest hydration, JSX runtime/compiler helpers, SSR, devtools, and logging bridges.
@shapeshift-labs/frontier-playwright: Playwright/headless automation probes for Frontier state, DOM, devtools, marks, and timeline queries.
@shapeshift-labs/frontier-crdt: Native CRDT documents, update tooling, awareness, branches, conflict introspection, version frames, and undo.
@shapeshift-labs/frontier-crdt-sync: CRDT sync endpoints, repo/storage/provider contracts, scheduled sync work, document URLs, local networks, model checking, forensics, and text binding contracts.
@shapeshift-labs/frontier-crdt-websocket: WebSocket client/server transports for Frontier CRDT sync providers.
@shapeshift-labs/frontier-react: React external-store hooks and adapters for Frontier state, cache, and CRDT surfaces.
@shapeshift-labs/frontier-richtext: Rich text Delta normalization/application, marks, embeds, ranges, and cursor/selection transforms for local editor integrations.
@shapeshift-labs/frontier-realtime: Shared realtime command, tick, snapshot, prediction, reconciliation, interpolation, rollback, message, and delta primitives.
@shapeshift-labs/frontier-realtime-server: Authoritative realtime room, tick, command validation, rate-limit, session, and snapshot-history runtime.
@shapeshift-labs/frontier-realtime-websocket: WebSocket client, wire, and Node room-server transport for Frontier realtime.
@shapeshift-labs/frontier-game: Game-facing entity, component, player, room, ownership, spatial interest, rollback, physics, and replication helpers above realtime.

Package source repositories:

Install

npm install @shapeshift-labs/frontier-workflow

Example

import {
  advanceWorkflowInstance,
  compileWorkflow,
  createWorkflowInstance,
  createWorkflowManifest,
  planWorkflowStep
} from '@shapeshift-labs/frontier-workflow';

const workflow = compileWorkflow(createWorkflowManifest({
  id: 'invoice.approval',
  startAt: 'draft',
  steps: [
    {
      id: 'draft',
      action: 'invoice.createDraft',
      writes: ['entities.invoices'],
      requires: ['invoice.write'],
      next: 'validate',
      compensation: [{ action: 'invoice.deleteDraft' }]
    },
    {
      id: 'validate',
      action: 'invoice.validate',
      retry: { maxAttempts: 3, initialDelayMs: 1000, backoff: 2 },
      next: 'approve'
    },
    {
      id: 'approve',
      wait: { approval: 'manager' },
      next: 'send'
    },
    {
      id: 'send',
      effect: 'fetch:/api/invoices/send',
      expectedPatch: [{ path: '/entities/invoices/:id/status', value: 'sent' }],
      compensation: [{ action: 'invoice.markSendFailed' }]
    }
  ]
}));

const instance = createWorkflowInstance(workflow, {
  id: 'invoice-run-1',
  input: { invoiceId: 'inv-1' }
});

const plan = planWorkflowStep(workflow, {
  instance,
  input: { id: 'inv-1' },
  dryRun: true
}, {
  capabilities: ['invoice.write']
});

const advanced = advanceWorkflowInstance(workflow, instance, {
  type: 'step.completed',
  stepId: 'draft',
  patches: [{ path: '/entities/invoices/inv-1/status', value: 'draft' }]
});

Surface

createWorkflowManifest, defineWorkflow, and defineWorkflowStep normalize serializable durable workflow graphs.
compileWorkflow indexes steps, transitions, dependencies, and waiters for repeated planning.
validateWorkflowManifest catches duplicate steps, unknown transitions, unknown dependencies, and unreachable steps.
createWorkflowInstance creates resumable workflow state with per-step attempts and status.
planWorkflowStep and planWorkflowStepAsync return policy-aware runnable/waiting/blocked plans with expected patch previews.
advanceWorkflowInstance applies start, completion, failure, signal, timer, approval, and cancellation events to an instance.
createWorkflowRecord, createWorkflowSession, and createWorkflowTimeline make replay/audit output explicit.
createWorkflowRegistryGraph and traceWorkflowImpact expose process steps to Frontier registry and impact queries.
encodeWorkflowJsonl, decodeWorkflowJsonl, redactWorkflowManifest, and createWorkflowProof support durable logs, redaction, and evidence bundles.

Policy And Runtime Bridges

Policy is structural. Pass a current decision or an evaluator:

const plan = await planWorkflowStepAsync(workflow, { instance }, {
  capabilities: ['invoice.write'],
  subject: { id: 'user:1' }
}, {
  policyEvaluator: async (request) => ({
    allowed: true,
    allowedSteps: [request.stepId],
    reasons: ['manager can advance invoice workflow']
  })
});

Runtime execution is also structural. A scheduler can consume plan.nextRetryAt and plan.waitingFor, an event log can persist record, trace can attach record.id, and effects/tools can execute plan.action or plan.effect without frontier-workflow importing those packages.

Research Notes

The first package pass incorporated ideas from Temporal TypeScript SDK, XState, AWS Amazon States Language tooling, and Inngest: explicit transitions, deterministic validation, durable step records, waits/signals/approvals, retry policy, compensation, and timeline/proof output.

Benchmarks

Package-local benchmark:

npm run bench

The package benchmark prints Frontier-only package measurements for manifest creation, compilation, validation, instance creation, planning, advancement, registry graph output, JSONL, and proofs.

Research comparison harness:

npm run bench:competitors

Competitor results are intentionally kept in benchmark artifacts and research notes rather than README claims.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@shapeshift-labs/frontier-workflow

Related Packages

Install

Example

Surface

Policy And Runtime Bridges

Research Notes

Benchmarks