@oomol-lab/open-flow 0.1.0-beta.76 → 0.1.0-beta.77

package/src/flow/common/change.ts

@@ -167,6 +167,7 @@ export interface ConditionNode extends GraphNodeBase {
 
 export type ManagedTaskExecutor =
   | import('../../http/common/httpRequest.ts').HttpRequestExecutor
+  | import('../../state/common/state.ts').DedupeExecutor
   | WorkflowExecutor
   | import('../../decision/common/decision.ts').DecisionExecutor
   | import('../../openapi/common/openapi.ts').OpenApiExecutor
@@ -397,7 +398,7 @@ export interface FlowDocument {
 
 export interface RevisionContent {
   readonly document: FlowDocument
-  readonly modelVersion: 2 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | typeof currentFlowModelVersion
+  readonly modelVersion: 2 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | typeof currentFlowModelVersion
   readonly modules: Readonly<Record<string, CodeModule>>
 }
 

package/src/flow/common/changeSchema.ts

@@ -6,6 +6,7 @@ import { limitDecisionTask } from '../../decision/common/decision.ts'
 import { assertHttpAuthBindings } from '../../http/common/authBindings.ts'
 import { isHttpHost, maxHttpHosts } from '../../http/common/hosts.ts'
 import { httpRequestExecutorSchema } from '../../http/common/httpRequest.ts'
+import { dedupeExecutorSchema } from '../../state/common/state.ts'
 import { checkJsonDepth } from './json.ts'
 import { retryConfigurationSchema } from './retry.ts'
 import { triggerScheduleSchema } from './triggerScheduleSchema.ts'
@@ -13,7 +14,7 @@ import { waitAutoContinueDraftSchema, waitAutoContinueSchema } from './wait.ts'
 import { webhookMethods } from './webhookMethod.ts'
 import { webhookResponseTimeout } from './webhookResponse.ts'
 
-export const currentFlowModelVersion = 12
+export const currentFlowModelVersion = 13
 const text = z.string()
 const actionConnection = text.describe(
   'Account selection: omit while unconfigured; use an account ID to select it; use "" to explicitly defer configuration. Deferred Actions fail if called; deferred Agent tools are excluded from the callable tool set. Not supported by Triggers.',
@@ -129,6 +130,7 @@ const managedFields = z.object({
     }),
     z.strictObject({ kind: z.literal('workflow'), flowId: text, revisionId: text }),
     httpRequestExecutorSchema,
+    dedupeExecutorSchema,
   ]),
 })
 
@@ -318,6 +320,7 @@ const revision = z.object({
     z.literal(9),
     z.literal(10),
     z.literal(11),
+    z.literal(12),
     z.literal(currentFlowModelVersion),
   ]),
   document,
@@ -723,6 +726,13 @@ export function changeOperationsSchema(kind?: string): JsonValue {
 }
 
 function checkModelVersion(content: RevisionContent): void {
+  if (
+    content.modelVersion < 13 &&
+    Object.values(content.document.graph.nodes).some(
+      (candidateNode) => candidateNode.kind === 'task' && 'executor' in candidateNode.task && candidateNode.task.executor.kind === 'dedupe',
+    )
+  )
+    throw new Error('Deduplication requires Flow model v13.')
   if (
     content.modelVersion < 12 &&
     Object.values(content.document.graph.nodes).some(

package/src/flow/common/errorHandling.ts

@@ -26,7 +26,7 @@ export const nodeErrorSchema = {
 } as const
 
 export function supportsNodeErrorHandling(node: GraphNode): boolean {
-  return supportsNodeRetry(node)
+  return supportsNodeRetry(node) || (node.kind === 'task' && 'executor' in node.task && node.task.executor.kind === 'dedupe')
 }
 
 export function nodeSystemOutputPorts(node: GraphNode): Readonly<Record<string, PortDefinition>> {

package/src/flow/common/semantics.ts

@@ -2,6 +2,7 @@ import { dequal } from 'dequal/lite'
 import { decisionTaskIssues } from '../../decision/common/decision.ts'
 import { httpRequestIssues, httpAuthHandles, httpRequestTask, httpRequestUrl } from '../../http/common/httpRequest.ts'
 import { openApiIssues, authHandles } from '../../openapi/common/openapi.ts'
+import { dedupeTask } from '../../state/common/state.ts'
 import { isTriggerNode } from './change.ts'
 import { nodeWorkflowReferences } from './workflowReferences.ts'
 export { renderPrompt } from './promptTemplate.ts'
@@ -273,6 +274,20 @@ export async function validateFlow(revision: RevisionContent, engine: EngineCont
       })
     for (const message of openApiIssues(task))
       checked.diagnostics.push({ code: 'openapi.config-invalid', column: 0, line: 1, message, path: `/document/graph/nodes/${nodeId}/task/executor` })
+    if (task.executor.kind === 'dedupe') {
+      const expected = dedupeTask(task.executor)
+      if (
+        !dequal(httpPortContracts(task.inputs), httpPortContracts(expected.inputs)) ||
+        !dequal(httpPortContracts(task.outputs), httpPortContracts(expected.outputs))
+      )
+        checked.diagnostics.push({
+          code: 'dedupe.ports-invalid',
+          column: 0,
+          line: 1,
+          message: 'Deduplication ports must match the fixed contract.',
+          path: `/document/graph/nodes/${nodeId}/task`,
+        })
+    }
     if (task.executor.kind == 'http-request') {
       for (const issue of httpRequestIssues(task.executor))
         checked.diagnostics.push({
@@ -440,6 +455,11 @@ const httpPortContracts = (ports: import('./change.ts').ManagedTaskDefinition['i
 export async function prepareFlow(revision: RevisionContent, engineContract: string, triggerId?: string): Promise<PrepareFlowResult> {
   const engine = findEngineContract(engineContract)
   if (engine == null) return { kind: 'engine-unsupported' }
+  if (
+    !engine.flowState &&
+    Object.values(revision.document.graph.nodes).some((node) => node.kind === 'task' && 'executor' in node.task && node.task.executor.kind === 'dedupe')
+  )
+    return { kind: 'engine-unsupported' }
   if (
     !engine.httpRequests &&
     Object.values(revision.document.graph.nodes).some((node) => node.kind == 'task' && 'executor' in node.task && node.task.executor.kind == 'http-request')

package/src/runtime/common/engineContract.ts

@@ -9,10 +9,11 @@ export interface EngineContract {
   readonly httpRequests?: boolean
   /** Code may call `context.fetch` for hosts declared by its `http` Capability. */
   readonly codeFetch?: boolean
+  readonly flowState?: boolean
 }
 
-/** v9 is a single contract: the Node compatibility builtins, `context.fetch`, and no `context.egress`. */
-export const currentEngineContract = 'open-flow-engine/v9'
+/** v10 adds persistent Flow State to the published v9 Node compatibility and fetch contract. */
+export const currentEngineContract = 'open-flow-engine/v10'
 /** The published v8 Node compatibility contract, retained for existing Publications and Runs. */
 export const nodejsEngineContract = 'open-flow-engine/v8/nodejs-compat-v1'
 
@@ -63,10 +64,12 @@ const nodejsContract: EngineContract = {
   platformSource: platformSource(nodejsEngineContract),
 }
 
-const currentContract: EngineContract = { ...nodejsContract, codeFetch: true, platformSource: platformSource(currentEngineContract) }
+const v9Contract: EngineContract = { ...nodejsContract, codeFetch: true, platformSource: platformSource('open-flow-engine/v9') }
+const currentContract: EngineContract = { ...v9Contract, flowState: true, platformSource: platformSource(currentEngineContract) }
 
 export function findEngineContract(contract: string): EngineContract | undefined {
   if (contract == currentEngineContract) return currentContract
+  if (contract == 'open-flow-engine/v9') return v9Contract
   if (contract == 'open-flow-engine/v8') return v8Contract
   if (contract == nodejsEngineContract) return nodejsContract
   if (contract == 'open-flow-engine/v7' || contract == 'open-flow-engine/v7/nodejs-compat-v1')

package/src/runtime/common/runtime.ts

@@ -5,6 +5,58 @@ import { currentEngineContract } from './engineContract.ts'
 
 export { currentEngineContract, nodejsEngineContract, findEngineContract, type EngineContract } from './engineContract.ts'
 
+/** Serialized into the guest; keep validation and helpers self-contained. */
+export function createState(invoke: (kind: string, payload: JsonValue) => Promise<RuntimeCapabilityResponse>) {
+  // Serialized into the guest together with this factory.
+  // oxlint-disable-next-line unicorn/consistent-function-scoping
+  const invalid = (message: string) => Object.assign(new TypeError(message), { code: 'capability.invalid' })
+  const keyOf = (key: unknown) => {
+    if (typeof key !== 'string' || key.length === 0 || new TextEncoder().encode(key).length > 256) throw invalid('State keys require 1 to 256 UTF-8 bytes.')
+    return key
+  }
+  const valueOf = (value: unknown): JsonValue => {
+    if (value === undefined) throw invalid('State values must be JSON.')
+    try {
+      return (snapshotRuntimeResult({ value }) as { value: JsonValue }).value
+    } catch {
+      throw invalid('State values must be JSON.')
+    }
+  }
+  const idsOf = (ids: unknown): (string | number)[] => {
+    if (!Array.isArray(ids) || !Array.from(ids).every((id) => typeof id === 'string' || (typeof id === 'number' && Number.isFinite(id))))
+      throw invalid('Identities must be strings or finite numbers.')
+    return ids
+  }
+  return {
+    state: Object.freeze({
+      async get(key: unknown) {
+        return ((await invoke('state.get', { key: keyOf(key) })).body as { value: JsonValue }).value
+      },
+      async set(key: unknown, value: unknown) {
+        await invoke('state.set', { key: keyOf(key), value: valueOf(value) })
+      },
+      async insert(key: unknown, value: unknown) {
+        if (value === null) throw invalid('State insert does not accept null.')
+        return ((await invoke('state.insert', { key: keyOf(key), value: valueOf(value) })).body as { inserted: boolean }).inserted
+      },
+      async delete(key: unknown) {
+        await invoke('state.delete', { key: keyOf(key) })
+      },
+      async list() {
+        return ((await invoke('state.list', {})).body as { keys: string[] }).keys
+      },
+    }),
+    dedupe: Object.freeze({
+      async insert(ids: unknown) {
+        return ((await invoke('dedupe.insert', { ids: idsOf(ids) })).body as { inserted: boolean[] }).inserted
+      },
+      async has(ids: unknown) {
+        return ((await invoke('dedupe.has', { ids: idsOf(ids) })).body as { present: boolean[] }).present
+      },
+    }),
+  }
+}
+
 export type RuntimeModule = Pick<CodeModule, 'imports' | 'source'>
 
 /** Snapshot a Task result before JSON transport can discard or coerce invalid values. */
@@ -391,6 +443,70 @@ async function rejects(operation: Promise<unknown>, pattern: RegExp, message: st
 }
 
 export const runtimeConformanceCases: readonly RuntimeConformanceCase[] = [
+  {
+    name: 'cancels detached State work when its Task finishes',
+    async verify(harness) {
+      let aborted = false
+      const result = await harness.invoke({
+        input: null,
+        invocationId: 'state-detached',
+        capability: async ({ signal }) =>
+          await new Promise((resolve) => {
+            signal.addEventListener(
+              'abort',
+              () => {
+                aborted = true
+                resolve({ status: 200, body: null })
+              },
+              { once: true },
+            )
+          }),
+        program: program(
+          harness,
+          `export default async (_, context) => {
+          void context.state.set('detached', 1);
+          await new Promise(resolve => setTimeout(resolve, 20));
+          return null;
+        }`,
+        ),
+      })
+      equal(result, null, 'Detached State Task result')
+      equal(aborted, true, 'Detached State cancellation')
+    },
+  },
+  {
+    name: 'rejects non-JSON State values and invalid identities before Host dispatch',
+    async verify(harness) {
+      let calls = 0
+      const result = await harness.invoke({
+        input: null,
+        invocationId: 'state-invalid',
+        capability: async () => {
+          calls += 1
+          return { status: 200, body: null }
+        },
+        program: program(
+          harness,
+          `export default async (_, context) => {
+          const cyclic = {}; cyclic.self = cyclic;
+          const invalid = [undefined, NaN, Infinity, new Date(), { x: undefined }, cyclic, [undefined], { x: () => 1 }];
+          const errors = [];
+          for (const value of invalid) { try { await context.state.set('key', value); errors.push('accepted'); } catch (e) { errors.push(e.code); } }
+          for (const call of [() => context.state.get(''), () => context.state.get('x'.repeat(257)), () => context.state.insert('x', null), () => context.dedupe.insert([NaN]), () => context.dedupe.has([null]), () => context.dedupe.insert(new Array(1))]) {
+            try { await call(); errors.push('accepted'); } catch (e) { errors.push(e.code); }
+          }
+          return errors;
+        }`,
+        ),
+      })
+      equal(
+        result,
+        Array.from({ length: 14 }, () => 'capability.invalid'),
+        'State boundary validation',
+      )
+      equal(calls, 0, 'State invalid dispatch')
+    },
+  },
   {
     name: 'rejects Task results that JSON transport would discard or coerce',
     async verify(harness) {

package/src/state/common/conformance.ts

@@ -0,0 +1,86 @@
+import type { JsonValue } from '../../flow/common/model.ts'
+import type { DedupeConfig } from './state.ts'
+
+import { dequal } from 'dequal/lite'
+
+export interface StateConformanceHarness {
+  readonly maxIdentities: number
+  /** Executes Code on the same initially empty Flow and scope on every call; returns its `result` output. */
+  run(source: string): Promise<JsonValue>
+  /** Executes the same dedupe node across Runs, updating its business config and items. */
+  dedupe(config: DedupeConfig, items: JsonValue[]): Promise<{ items: JsonValue[]; duplicates: JsonValue[] }>
+}
+
+export const stateConformanceCases: readonly { name: string; verify(harness: StateConformanceHarness): Promise<void> }[] = [
+  {
+    name: 'persists watermarks by instant and resets changed modes atomically',
+    async verify(harness) {
+      const config: DedupeConfig = { field: '', mode: 'increasing', space: 'node' }
+      const first = await harness.dedupe(config, ['2026-10-30T09:00:00+08:00', '2026-10-30T01:00:00Z', '2026-10-30T02:00:00Z'])
+      if (!dequal(first, { items: ['2026-10-30T09:00:00+08:00', '2026-10-30T02:00:00Z'], duplicates: ['2026-10-30T01:00:00Z'] }))
+        throw new Error('Watermarks must compare instants and preserve item order.')
+      let rejected = false
+      try {
+        await harness.dedupe(config, [1])
+      } catch {
+        rejected = true
+      }
+      if (!rejected) throw new Error('Mixed watermark types must fail.')
+      const second = await harness.dedupe(config, ['2026-10-30T02:00:00Z', '2026-10-30T03:00:00Z'])
+      if (!dequal(second, { items: ['2026-10-30T03:00:00Z'], duplicates: ['2026-10-30T02:00:00Z'] }))
+        throw new Error('A failed batch must preserve the previous watermark.')
+      await harness.dedupe({ ...config, mode: 'new' }, [])
+      const reset = await harness.dedupe(config, [5, 3, 5])
+      if (!dequal(reset, { items: [5, 3], duplicates: [5] })) throw new Error('A mode reset must discard previous watermarks, including on empty batches.')
+    },
+  },
+  {
+    name: 'round-trips independent JSON values and deletes without exposing stored references',
+    async verify(harness) {
+      const result = await harness.run(`export default async (_, context) => {
+        await context.state.set('b', { nested: [1, null, false] });
+        const copy = await context.state.get('b');
+        copy.nested.push(2);
+        const retained = await context.state.get('b');
+        const inserted = await context.state.insert('b', 'replacement');
+        await context.state.set('a', 0);
+        const keys = await context.state.list();
+        await context.state.delete('a');
+        await context.state.set('b', null);
+        return {result: {retained, inserted, keys, missing: await context.state.get('a'), remaining: await context.state.list()}};
+      }`)
+      if (!dequal(result, { retained: { nested: [1, null, false] }, inserted: false, keys: ['a', 'b'], missing: null, remaining: [] }))
+        throw new Error('State JSON round-trip, conditional insertion or deletion differs from the contract.')
+    },
+  },
+  {
+    name: 'persists explicit values and dedupe history across Runs',
+    async verify(harness) {
+      const source = `export default async (_, context) => {
+        const first = await context.state.insert('count', 0);
+        const count = await context.state.get('count');
+        await context.state.set('count', count + 1);
+        return { result: { first, count, ids: await context.dedupe.insert(['a', 'a']) } };
+      }`
+      if (
+        !dequal(await harness.run(source), { first: true, count: 0, ids: [true, false] }) ||
+        !dequal(await harness.run(source), { first: false, count: 1, ids: [false, false] })
+      )
+        throw new Error('State must persist across Runs without replacing existing values on insert.')
+    },
+  },
+  {
+    name: 'rejects a full batch atomically while permitting duplicates at capacity',
+    async verify(harness) {
+      const result = await harness.run(`export default async (_, context) => {
+        const ids = Array.from({length: ${harness.maxIdentities}}, (_, index) => index);
+        await context.dedupe.insert(ids);
+        let error;
+        try { await context.dedupe.insert([0, 'extra']); } catch (failure) { error = failure.code; }
+        return { result: { error, extra: await context.dedupe.has(['extra']), duplicate: await context.dedupe.insert([0, 0]) } };
+      }`)
+      if (!dequal(result, { error: 'dedupe.full', extra: [false], duplicate: [false, false] }))
+        throw new Error('Dedupe capacity must fail atomically and preserve duplicate membership.')
+    },
+  },
+]

package/src/state/common/state.ts

@@ -0,0 +1,169 @@
+import type { JsonValue, ManagedTaskDefinitionOf } from '../../flow/common/model.ts'
+
+import { z } from 'zod'
+
+export { stateConformanceCases, type StateConformanceHarness } from './conformance.ts'
+
+export type StateScope = 'draft' | 'live'
+export const stateQuerySchema = z.strictObject({ scope: z.enum(['draft', 'live']), values: z.boolean().optional() })
+export const stateClearSchema = z.strictObject({
+  scope: z.enum(['draft', 'live']),
+  key: z
+    .string()
+    .min(1)
+    .refine((key) => new TextEncoder().encode(key).length <= 256)
+    .optional(),
+})
+export const dedupeClearSchema = z.strictObject({ scope: z.enum(['draft', 'live']), space: z.string().regex(/^(flow|node:.+)$/) })
+export type DedupeIdentity = string | number
+export const dedupeConfigSchema = z.strictObject({
+  field: z.string().default(''),
+  mode: z.enum(['new', 'increasing']).default('new'),
+  space: z.enum(['node', 'flow']).default('node'),
+})
+export type DedupeConfig = z.infer<typeof dedupeConfigSchema>
+export interface DedupeExecutor extends DedupeConfig {
+  readonly kind: 'dedupe'
+}
+export const dedupeExecutorSchema = dedupeConfigSchema.extend({ kind: z.literal('dedupe') })
+
+export function dedupeTask(config: DedupeConfig = dedupeConfigSchema.parse({}), name = 'Remove Duplicates'): ManagedTaskDefinitionOf<DedupeExecutor> {
+  return {
+    name,
+    executor: { ...config, kind: 'dedupe' },
+    inputs: [{ handle: 'items', jsonSchema: { type: 'array' }, nullable: false }],
+    outputs: ['items', 'duplicates'].map((handle) => ({ handle, jsonSchema: { type: 'array' }, nullable: false })),
+  }
+}
+
+export class StateError extends Error {
+  readonly retryable = false
+  readonly catchable: boolean
+  readonly code: 'capability.invalid' | 'capability.denied' | 'dedupe.full' | 'limit-exceeded'
+
+  constructor(code: StateError['code'], message: string) {
+    super(message)
+    this.name = 'StateError'
+    this.code = code
+    this.catchable = code === 'dedupe.full'
+  }
+}
+
+export function stateKey(key: unknown): string {
+  if (typeof key !== 'string' || key.length === 0 || new TextEncoder().encode(key).length > 256)
+    throw new StateError('capability.invalid', 'State keys require 1 to 256 UTF-8 bytes.')
+  return key
+}
+
+export function dedupeIdentities(value: unknown): DedupeIdentity[] {
+  if (!Array.isArray(value) || !Array.from(value).every((id) => typeof id === 'string' || (typeof id === 'number' && Number.isFinite(id))))
+    throw new StateError('capability.invalid', 'Identities must be strings or finite numbers.')
+  return value
+}
+
+export async function hashIdentities(ids: readonly DedupeIdentity[]): Promise<Uint8Array[]> {
+  return Promise.all(
+    ids.map(async (id) => new Uint8Array(await crypto.subtle.digest('SHA-256', new TextEncoder().encode(`${typeof id}:${String(id)}`))).slice(0, 16)),
+  )
+}
+
+export function watermarkValue(id: DedupeIdentity): number {
+  if (typeof id === 'number') {
+    if (!Number.isFinite(id)) throw new StateError('capability.invalid', 'Watermarks must be finite.')
+    return id
+  }
+  const match = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.(\d{1,3}))?(Z|[+-]\d{2}:\d{2})$/.exec(id)
+  if (match == null) throw new StateError('capability.invalid', 'Watermarks require RFC 3339 timestamps with an explicit timezone.')
+  const [, year, month, day, hour, minute, second, , zone] = match
+  const y = Number(year)
+  const days = [31, y % 4 === 0 && (y % 100 !== 0 || y % 400 === 0) ? 29 : 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31][Number(month) - 1] ?? 0
+  const result = Date.parse(id)
+  if (
+    Number(month) < 1 ||
+    Number(month) > 12 ||
+    Number(day) < 1 ||
+    Number(day) > days ||
+    Number(hour) > 23 ||
+    Number(minute) > 59 ||
+    Number(second) > 59 ||
+    (zone !== 'Z' && (Number(zone!.slice(1, 3)) > 23 || Number(zone!.slice(4)) > 59)) ||
+    !Number.isFinite(result)
+  )
+    throw new StateError('capability.invalid', 'Watermarks require valid calendar timestamps.')
+  return result
+}
+
+export function increasingIdentities(ids: readonly DedupeIdentity[], watermark: DedupeIdentity | null) {
+  const type = typeof (watermark ?? ids[0])
+  if (ids.some((id) => typeof id !== type)) throw new StateError('capability.invalid', 'Watermark types must not be mixed.')
+  const initial = watermark == null ? -Infinity : watermarkValue(watermark)
+  const seen = new Set<number>()
+  let maximum = initial
+  let next = watermark
+  const inserted = ids.map((id) => {
+    const value = watermarkValue(id)
+    const fresh = value > initial && !seen.has(value)
+    seen.add(value)
+    if (value > maximum) {
+      maximum = value
+      next = id
+    }
+    return fresh
+  })
+  return { inserted, watermark: next }
+}
+
+export function itemIdentities(items: JsonValue, field: string): DedupeIdentity[] {
+  if (!Array.isArray(items)) throw new StateError('capability.invalid', 'Deduplication requires an array of items.')
+  const path = field === '' ? [] : field.split('.')
+  return dedupeIdentities(
+    items.map((item) =>
+      path.reduce<JsonValue | undefined>(
+        (value, key) => (value != null && typeof value === 'object' && Object.hasOwn(value, key) ? (value as Record<string, JsonValue>)[key] : undefined),
+        item,
+      ),
+    ),
+  )
+}
+
+export interface FlowStateView {
+  readonly version: 1
+  readonly scope: StateScope
+  readonly limits: {
+    readonly maxValueBytes: number
+    readonly maxValues: number
+    readonly maxSpaces: number
+    readonly maxIdentities: number
+    readonly maxRunWrites: number
+  }
+  readonly values: readonly { readonly key: string; readonly size: number; readonly updatedAt: number; readonly value?: JsonValue }[]
+  readonly spaces: readonly {
+    readonly space: string
+    readonly mode: 'new' | 'increasing'
+    readonly count: number
+    readonly watermark: DedupeIdentity | null
+    readonly updatedAt: number
+  }[]
+}
+
+export const flowStateViewSchema = z.object({
+  version: z.literal(1),
+  scope: z.enum(['draft', 'live']),
+  limits: z.object({
+    maxValueBytes: z.number().positive(),
+    maxValues: z.number().int().positive(),
+    maxSpaces: z.number().int().positive(),
+    maxIdentities: z.number().positive(),
+    maxRunWrites: z.number().positive(),
+  }),
+  values: z.array(z.object({ key: z.string(), size: z.number().nonnegative(), updatedAt: z.number(), value: z.json().optional() })),
+  spaces: z.array(
+    z.object({
+      space: z.string(),
+      mode: z.enum(['new', 'increasing']),
+      count: z.number().nonnegative(),
+      watermark: z.union([z.string(), z.number(), z.null()]),
+      updatedAt: z.number(),
+    }),
+  ),
+})

package/src/types/index.ts

@@ -119,6 +119,17 @@ export interface TaskContext<
   readonly inputs: Readonly<Record<string, unknown>>
   readonly runId: string
   readonly blockId: string
+  readonly state: {
+    get(key: string): Promise<JsonValue | null>
+    set(key: string, value: JsonValue): Promise<void>
+    insert(key: string, value: Exclude<JsonValue, null>): Promise<boolean>
+    delete(key: string): Promise<void>
+    list(): Promise<string[]>
+  }
+  readonly dedupe: {
+    insert(ids: readonly (string | number)[]): Promise<boolean[]>
+    has(ids: readonly (string | number)[]): Promise<boolean[]>
+  }
   readonly artifact: ArtifactCapability
   /** Reads the selected direct predecessors, sorted by node ID; empty for a graph root. */
   getPrevious(): Promise<readonly PreviousNode[]>