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

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) {
@@ -935,14 +1051,13 @@ export function createBase64() {
       const padding = text.endsWith('==') ? 2 : text.endsWith('=') ? 1 : 0
       const bytes = new Uint8Array((text.length / 4) * 3 - padding)
       for (let index = 0, offset = 0; index < text.length; index += 4) {
-        const digits = [0, 1, 2, 3].map((position) => {
+        let value = 0
+        for (let position = 0; position < 4; position++) {
           const code = text.charCodeAt(index + position)
-          if (code == 61 && index + position >= text.length - padding) return 0
-          const value = code < 128 ? values[code]! : 255
-          if (value == 255) throw new TypeError('Base64 content is invalid.')
-          return value
-        })
-        const value = (digits[0]! << 18) | (digits[1]! << 12) | (digits[2]! << 6) | digits[3]!
+          const digit = code == 61 && index + position >= text.length - padding ? 0 : code < 128 ? values[code]! : 255
+          if (digit == 255) throw new TypeError('Base64 content is invalid.')
+          value = (value << 6) | digit
+        }
         if (offset < bytes.length) bytes[offset++] = value >> 16
         if (offset < bytes.length) bytes[offset++] = (value >> 8) & 255
         if (offset < bytes.length) bytes[offset++] = value & 255

package/src/state/common/conformance.ts

@@ -0,0 +1,81 @@
+import type { JsonValue } from '../../flow/common/model.ts'
+import type { SkipDuplicatesConfig } 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 Skip Duplicates node across Runs, updating its business config and items. */
+  skipDuplicates(config: SkipDuplicatesConfig, items: JsonValue[]): Promise<{ items: JsonValue[]; duplicates: JsonValue[] }>
+}
+
+export const stateConformanceCases: readonly { name: string; verify(harness: StateConformanceHarness): Promise<void> }[] = [
+  {
+    name: 'skips composite identities across successful Runs without depending on field order',
+    async verify(harness) {
+      const items = [
+        { company: 'a', id: 1 },
+        { company: 'b', id: 1 },
+        { company: 'a', id: 1 },
+      ]
+      const first = await harness.skipDuplicates({ fields: ['company', 'id'] }, items)
+      if (!dequal(first, { items: items.slice(0, 2), duplicates: [items[2]] }))
+        throw new Error('Composite identities must retain the first item in input order.')
+      const second = await harness.skipDuplicates({ fields: ['id', 'company'] }, items)
+      if (!dequal(second, { items: [], duplicates: items })) throw new Error('Successful Run history must persist independently of field order.')
+      const changed = await harness.skipDuplicates({ fields: ['id'] }, items)
+      if (!dequal(changed, { items: [items[0]], duplicates: items.slice(1) })) throw new Error('The field definition must participate in identity.')
+    },
+  },
+  {
+    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,141 @@
+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 skipDuplicatesConfigSchema = z.strictObject({
+  fields: z
+    .array(z.string().refine((field) => field.length > 0 && field.split('.').every((part) => part.length > 0), 'Use a nonempty dot-separated field path.'))
+    .refine((fields) => new Set(fields).size === fields.length, 'Identity fields must be distinct.')
+    .default([]),
+})
+export type SkipDuplicatesConfig = z.infer<typeof skipDuplicatesConfigSchema>
+export interface SkipDuplicatesExecutor extends SkipDuplicatesConfig {
+  readonly kind: 'skip-duplicates'
+}
+export const skipDuplicatesExecutorSchema = skipDuplicatesConfigSchema.extend({ kind: z.literal('skip-duplicates') })
+
+export function skipDuplicatesTask(
+  config: SkipDuplicatesConfig = skipDuplicatesConfigSchema.parse({}),
+  name = 'Skip Duplicates',
+): ManagedTaskDefinitionOf<SkipDuplicatesExecutor> {
+  return {
+    name,
+    executor: { ...config, kind: 'skip-duplicates' },
+    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' | 'node.input-invalid'
+
+  constructor(code: StateError['code'], message: string) {
+    super(message)
+    this.name = 'StateError'
+    this.code = code
+    this.catchable = code === 'dedupe.full' || code === 'node.input-invalid'
+  }
+}
+
+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)),
+  )
+}
+
+/** Canonical identities include the field definition and preserve scalar types. */
+export function skipDuplicatesIdentities(items: JsonValue, fields: readonly string[]): string[] {
+  if (!Array.isArray(items)) throw new StateError('node.input-invalid', 'Skip Duplicates requires an array of items.')
+  const paths = fields.toSorted()
+  return items.map((item, index) => {
+    const values = (paths.length === 0 ? [''] : paths).map((field) => {
+      const value =
+        field === ''
+          ? item
+          : field
+              .split('.')
+              .reduce<JsonValue | undefined>(
+                (current, key) =>
+                  current != null && typeof current === 'object' && Object.hasOwn(current, key) ? (current as Record<string, JsonValue>)[key] : undefined,
+                item,
+              )
+      if (typeof value !== 'string' && !(typeof value === 'number' && Number.isFinite(value)))
+        throw new StateError(
+          'node.input-invalid',
+          `Item ${index + 1}, ${field === '' ? 'the item itself' : `field ${JSON.stringify(field)}`} must be a string or finite number.`,
+        )
+      return value
+    })
+    return JSON.stringify([paths, values])
+  })
+}
+
+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 count: number
+    readonly pendingCount: number
+    readonly reservedCount: number
+    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(),
+      count: z.number().nonnegative(),
+      pendingCount: z.number().nonnegative(),
+      reservedCount: z.number().nonnegative(),
+      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[]>