@t4h.framework/core 0.6.1 → 0.8.0

package/.ai/skills/framework-core/SKILL.md

@@ -1,23 +1,32 @@
 ---
 name: framework-core
 description: >-
-  Author and test T4H Framework workflows, SyncActivity/AsyncActivity classes,
-  Claim dependencies, App manifests, env access, and in-memory workflow runs.
-  Use when importing @t4h.framework/core, building automation apps, orchestrating
-  with History.reconciler, wiring Claim providers, testing with
-  @t4h.framework/core/testing (WorkflowTesting, mockAsyncActivity), nested
-  startWorkflow, EnvDesign, Authorization manifests, or Internals.runWorkflow /
-  Internals.runActivity.
+  Build, register, and test T4H Framework workflows with @t4h.framework/core:
+  the Workflow and App author API, env/EnvDesign configuration, nested workflows
+  via startWorkflow, Serializable/Authorization manifests, and the in-memory
+  TestWorkflowEnvironment. Use when importing @t4h.framework/core to create a
+  Workflow or App, wire env, orchestrate nested workflows, or test workflows
+  with @t4h.framework/core/testing. Core composes with the other framework
+  packages (@t4h.framework/http, @t4h.framework/sleep, …) that do the real work.
 ---
 
 # @t4h.framework/core
 
-Core primitives for **Workflows** (orchestration), **Activities** (work units), and **Claims** (runtime dependencies). The runtime supplies `env`, `claims`, and `history`; this package defines the author API and in-memory test harness.
+Core is the **orchestration layer** of the T4H Framework. A workflow is a deterministic,
+replay-safe async function you register in an **App**. This package gives you the author
+API (`Workflow`, `App`, `env`, `startWorkflow`) and an in-memory test harness. The actual
+side effects — HTTP requests, delays, storage — come from the companion packages you
+compose inside the workflow body.
+
+> **Building a workflow?** You only need the primitives on this page plus the package(s)
+> that do the real work — `@t4h.framework/http` for HTTP, `@t4h.framework/sleep` for
+> delays, and so on. You do **not** implement any of the framework's internal building
+> blocks to write a workflow.
 
 | Import | Purpose |
 |--------|---------|
-| `@t4h.framework/core` | Workflows, activities, claims, app, env, internals |
-| `@t4h.framework/core/testing` | `WorkflowTesting` — tests/local only |
+| `@t4h.framework/core` | `Workflow`, `App`, `env`, `EnvDesign`, `startWorkflow`, `Serializable`/`Binary`, `Authorization` |
+| `@t4h.framework/core/testing` | `TestWorkflowEnvironment` — tests/local only |
 
 Node `>=22`. Schemas use TypeBox (`typebox`). See [README.md](../../../README.md) for diagrams.
 
@@ -25,12 +34,11 @@ Node `>=22`. Schemas use TypeBox (`typebox`). See [README.md](../../../README.md
 
 ## Concepts
 
-- **Workflow** — orchestration; composes activities via `History.reconciler` (or helpers like `startWorkflow`).
-- **Activity** — `SyncActivity` (`toInput` → `run` → `toOutput`) or `AsyncActivity` (`toInput` → `bootstrap` → `advance` → `toOutput`, optional `onTimeout`).
-- **Claim** — abstract class; activity maps keys → constructors; runtime provides `{ provide, value }`.
-- **History** — replay: existing history entries skip execution; missing entries run activity and record result (`PushActivity`).
-
-Async helpers on `AsyncActivity`: `this.pending()`, `this.done()`, `this.rejected()`.
+- **Workflow** — an orchestration entrypoint: a plain async function wrapped in `new Workflow(...)`. It coordinates steps; it does not implement the steps.
+- **App** — registers workflows so the runtime can discover and run them.
+- **Replay & determinism** — the runtime may re-run a workflow from its recorded history. Keep the body deterministic: branch on inputs and on the results of the steps you call, never on `Date.now()`, `Math.random()`, or ambient state. Use framework primitives (e.g. `sleep`) when you need time to pass.
+- **env** — configuration values supplied by the runtime; the single source for URLs, tokens, and tenants.
+- **Composition** — external work is performed by calling primitives from the other framework packages inside the workflow body.
 
 ---
 
@@ -38,7 +46,7 @@ Async helpers on `AsyncActivity`: `this.pending()`, `this.done()`, `this.rejecte
 
 ```typescript
 import Type from 'typebox'
-import { Workflow, env } from '@t4h.framework/core'
+import { Workflow } from '@t4h.framework/core'
 
 const bare = new Workflow(async () => ({ ok: true }))
 
@@ -53,141 +61,26 @@ const validated = new Workflow({ id: 'cashback/v1', schema }, async input => ({
 }))
 ```
 
-- `new Workflow(fn)` or `new Workflow(options, fn)` — bad overload throws `Invalid constructor arguments`.
-- `WorkflowInput<T>` — from schema; `undefined` without schema.
-- `workflow.validate` — Ajv when `schema` set; else `null`.
-- Optional `authorization` on workflow/app → `toManifest()`.
-
----
-
-## Invoking activities
-
-```typescript
-import { History } from '@t4h.framework/core'
-
-const syncResult = await History.reconciler(MySyncActivity, arg1)
-
-const handle = await History.reconciler(WaitAsyncActivity, 'order-1')
-const out = await handle.wait()
-```
-
-- No history: `toInput` then `PushActivity` → runtime runs `run`/`bootstrap`.
-- Replay: uses stored output; async returns `AsyncActivityAwaitable`; `wait()` throws `PushWaitAsyncActivity` if still `pending`.
-- Must run inside `History.run` (workflow runtime / `WorkflowTesting` provide this).
-
----
-
-## SyncActivity
-
-```typescript
-import { SyncActivity } from '@t4h.framework/core'
-
-class CalculateCashbackActivity extends SyncActivity<
-  [transaction: { amount: number }], // TArgs
-  { amount: number },                  // TInput (Serializable)
-  number,                              // TSerializableOutput
-  number                               // TOutput
-> {
-  public async toInput(transaction: { amount: number }) {
-    return { amount: transaction.amount }
-  }
-  public run(input: { amount: number }) {
-    return Math.floor(input.amount * 0.05)
-  }
-  public toOutput(output: number) {
-    return output
-  }
-}
-```
-
-`toOutput(output, ...args)` receives original designer args.
-
----
-
-## AsyncActivity
-
-```typescript
-import Type from 'typebox'
-import { AsyncActivity, AsyncActivityResultPending } from '@t4h.framework/core'
-
-const ApprovalSchema = Type.Object({ approved: Type.Boolean() })
-
-class WaitForApprovalActivity extends AsyncActivity<
-  [orderId: string],
-  { orderId: string },
-  { approved: boolean },
-  { approved: boolean },
-  { requestId: string; orderId: string },
-  typeof ApprovalSchema
-> {
-  public async toInput(orderId: string) {
-    return { orderId }
-  }
-  public async bootstrap(input: { orderId: string }) {
-    return this.pending({
-      payload: { requestId: 'req-123', orderId: input.orderId },
-      schema: ApprovalSchema,
-      timeoutAt: new Date(Date.now() + 3_600_000),
-    })
-  }
-  public async advance(
-    payload: Type.Static<typeof ApprovalSchema>,
-    bootstrap: AsyncActivityResultPending<{ requestId: string; orderId: string }>,
-  ) {
-    return payload.approved
-      ? this.done({ approved: true })
-      : this.rejected({ approved: false, requestId: bootstrap.payload?.requestId })
-  }
-  public toOutput(output: { approved: boolean }) {
-    return output
-  }
-}
-```
-
-Results: `AsyncActivityResultPending` | `AsyncActivityResultFulfilled` | `AsyncActivityResultRejected`. Default `onTimeout` → `rejected({ reason: 'timeout' })`.
-
----
-
-## Claims
-
-```typescript
-import { SyncActivity, Claim } from '@t4h.framework/core'
-
-abstract class UserRepositoryClaim {
-  abstract findById(id: string): Promise<unknown>
-}
-
-class FetchUserActivity extends SyncActivity<[id: string], { id: string }, unknown, unknown> {
-  private readonly claims = new Claim({ repo: UserRepositoryClaim })
-
-  public async toInput(id: string) {
-    return { id }
-  }
-  public async run(input: { id: string }) {
-    return await this.claims.repo.findById(input.id)
-  }
-  public toOutput(output: unknown) {
-    return output
-  }
-}
-```
-
-Provider: `{ provide: UserRepositoryClaim, value: impl }`. Built-ins: `GetWorkflowUniqueIdentifierClaim`, `GetActivityUniqueIdentifierClaim`, `WorkflowClaim` (for `startWorkflow`).
-
-Exceptions: `ClaimKeyNotFoundException`, `ClaimConstructorNotFoundException`, `ClaimStorageNotActiveException`, `ClaimProviderNotFoundException`. Access `claims.*` only inside `Claim.run`.
+- `new Workflow(fn)` or `new Workflow(options, fn)` — a bad overload throws `Invalid constructor arguments`.
+- `WorkflowInput<T>` — derived from `schema`; `undefined` when no schema is set.
+- `workflow.validate` — an Ajv validator when `schema` is set; otherwise `null`.
+- Optional `authorization` on a workflow or app surfaces in `toManifest()`.
 
 ---
 
 ## Nested workflows
 
 ```typescript
-import { startWorkflow, WorkflowClaim } from '@t4h.framework/core'
+import { Workflow, startWorkflow } from '@t4h.framework/core'
+import { childWorkflow } from './child-workflow.js'
 
-const ref = await startWorkflow(childWorkflow, { ...input, parallel?: boolean })
-// WorkflowRef: status 'fulfilled' | 'rejected', output Serializable
+export const parent = new Workflow({ id: 'parent' }, async input => {
+  const ref = await startWorkflow(childWorkflow, { ...input, parallel: false })
+  return ref.output // WorkflowRef: status 'fulfilled' | 'rejected', output Serializable
+})
 ```
 
-`StartWorkflowActivity`: `parallel: true` → immediate `done`; else `pending` until `advance`. Requires `WorkflowClaim` provider.
+`parallel: true` returns as soon as the child starts; otherwise the parent waits for the child to settle.
 
 ---
 
@@ -204,200 +97,123 @@ const app = new App({
 app.addWorkflow(anotherWorkflow) // throws on duplicate workflow.id
 ```
 
-`toManifest()` includes workflows + registered `EnvDesign` entries.
+`toManifest()` includes the registered workflows plus any `EnvDesign` entries.
 
 ---
 
 ## Environment
 
-```typescript
-import { env, EnvDesign } from '@t4h.framework/core'
+**Always configure environment access through `EnvDesign`** — not the raw `env` proxy. `EnvDesign` gives you typed, validated, self-documenting configuration that also feeds the app manifest automatically. Reach for raw `env` only for a one-off, dynamic key that can't be declared ahead of time.
 
-// Under Env.run — string values
-console.log(env.API_URL)
+### The standard: one `constants/environments.ts` with the `EnvDesign`
+
+Declare **every** env var the project needs in a single `EnvDesign` and export it. Import that one object anywhere you need configuration.
+
+```typescript
+// src/constants/environments.ts
+import { EnvDesign } from '@t4h.framework/core'
 
-// Typed parsing (registers for app manifest)
-const config = EnvDesign({
+export const environments = EnvDesign({
   API_URL: { type: String },
   RETRIES: { type: Number, defaultValue: '3' },
   DEBUG: { type: Boolean, isOptional: true },
+  // custom parser: raw string -> your type
+  REAJUSTE_INDICES: { type: (raw: string) => JSON.parse(raw) as Record<string, number> },
 })
 ```
 
----
-
-## Serializable & Authorization
-
-**Serializable:** primitives, `null`, `undefined`, `Binary`, `SerializableClass`, arrays/objects thereof. `Binary`: `contentType`, `contentLength`, `stream()`.
-
-**Authorization:** subclass with `toManifest(): AuthorizationManifest` (`pathToModule`, optional `context`); attach to `Workflow` or `App`.
-
----
-
-## Internals (runtime / unit tests)
-
 ```typescript
-import { Internals } from '@t4h.framework/core'
-
-Internals.runWorkflow(workflow, {
-  input,
-  env: { API_URL: 'https://api.example.com' },
-  claims: [{ provide: UserRepositoryClaim, value: impl }],
-  history: [],
-  logs: [],
-})
-
-Internals.runActivity(FetchUserActivity, { env, claims }, a => a.run({ id: '123' }))
-```
-
-Stack: `Env.run` → `Claim.run` → `History.run` → `Logger.run` (workflows). **Test `advance` here** — not via `WorkflowTesting`.
-
----
-
-## Testing (`@t4h.framework/core/testing`)
-
-Test-only entrypoint — **not** part of the production runtime contract. Import from the subpath export:
+// anywhere — a workflow, a helper, etc.
+import { environments } from '../constants/environments.js'
 
-```typescript
-import { WorkflowTesting } from '@t4h.framework/core/testing'
+const res = await http.get(`${environments.API_URL}/status`) // string
+if (environments.RETRIES > 0) { /* number, parsed */ }
 ```
 
-`package.json` maps `"./testing"` → `dist/testing/index.js`. The public API is **`WorkflowTesting.run`** only.
+**Why this is safe and preferred:**
 
-### `WorkflowTesting.run`
+- `EnvDesign({...})` does **not** read `env` at construction — only when you access a key (`environments.API_URL`). So the top-level `export const environments = EnvDesign(...)` is safe at import time; the read + parse + validation happen lazily, inside a running workflow.
+- Access **keys inside the workflow body / functions**, never at module top level — reading a key outside a run throws (`env` has no storage until the runtime executes the workflow).
+- Each key is parsed to its declared `type` (`String` | `Number` | `Boolean` | a custom `(raw: string) => T` parser), `defaultValue` fills in when unset, and `isOptional: true` allows `undefined` instead of throwing.
+- A required key that is unset throws `Environment variable X is not set` on access — fail-fast, no silent `undefined`.
+- Declaring via `EnvDesign` registers the entry in the **app manifest** (`app.toManifest().env`) automatically — the runtime knows exactly which vars the app requires.
 
-```typescript
-const output = await WorkflowTesting.run(workflow, input?, options?)
-```
+Never inline URLs, secrets, tokens, or tenants in workflow code; never read `process.env` directly.
 
-| Option | Type | Default | Purpose |
-|--------|------|---------|---------|
-| `claims` | `readonly ClaimProvider[]` | `[]` | Concrete claim implementations for the run |
-| `env` | `Env.Entries` | `{}` | String env vars (`Env.run`) |
-| `mockAsyncActivity` | function \| outcome array | — | Required when any async activity returns `pending` |
-| `logs` | `Log[]` | internal | Capture `console.log` / `console.error` once per run |
-| `maxTicks` | `number` | `10_000` | Max activity-resolution loops before error |
+---
 
-Typed input follows `WorkflowInput<T>` when the workflow has a `schema`; omit `input` for workflows without one.
+## Serializable & Authorization
 
-### How the driver works
+**Serializable:** primitives, `null`, `undefined`, `Binary`, `SerializableClass`, and arrays/objects thereof. Workflow input, output, and every value that crosses a step boundary must be `Serializable`. `Binary`: `contentType`, `contentLength`, `stream()`.
 
-1. Calls `Internals.runWorkflow` with an empty `history`.
-2. On **`PushActivity`**, runs the pushed activity in-process:
-   - **Sync:** `Internals.runActivity` → `run(input)` → append `{ type: 'sync', output }` to history.
-   - **Async:** real `bootstrap`; if already `done`/`rejected`, record and continue; if **`pending`**, apply `mockAsyncActivity` (throws if missing).
-3. Re-runs the workflow with accumulated history until it returns normally or `maxTicks` is exceeded.
+**Authorization:** subclass with `toManifest(): AuthorizationManifest` (`pathToModule`, optional `context`); attach to a `Workflow` or `App`.
 
-This drives sync activities end-to-end and async activities through bootstrap + mocked resolution — **not** through real `advance`.
+---
 
-### Wiring claims in tests
+## Testing (`@t4h.framework/core/testing`)
 
-Pass explicit `{ provide, value }` providers — same shape as `Internals.runWorkflow`:
+Test-only entrypoint — **not** part of the production runtime contract. `package.json` maps `"./testing"` → `dist/testing/index.js`.
 
 ```typescript
-import { WorkflowTesting } from '@t4h.framework/core/testing'
-import { History, type Log } from '@t4h.framework/core'
+import { TestWorkflowEnvironment } from '@t4h.framework/core/testing'
 
-const logs: Log[] = []
-const output = await WorkflowTesting.run(workflow, input, {
+const env = TestWorkflowEnvironment.create({ now: 0 })
+const output = await env.execute(workflow, input, {
   env: { API_URL: 'https://example.com' },
-  claims: [{ provide: UserRepositoryClaim, value: mockRepo }],
-  mockAsyncActivity: () => ({ status: 'fulfilled', output: true }),
-  logs,
+  claims: [/* provider implementations required by the packages your workflow uses */],
 })
 ```
 
-For a single activity, prefer `Claim.run([...], fn)` or `Internals.runActivity`. Use `WorkflowTesting.run` for full workflow integration tests.
+`create()` options:
 
-### `mockAsyncActivity`
+| Option | Default | Purpose |
+|--------|---------|---------|
+| `now` | `0` | Pins `Date.now()` to this value at run start |
+| `resolveActivityTimeouts` | `true` | Auto-advances the clock through time-based steps (e.g. `sleep`) and resolves them |
 
-Required when `bootstrap` returns `pending`:
+`execute()` options:
 
-| `status` | Effect |
-|----------|--------|
-| `fulfilled` | `{ output }` recorded as async fulfilled |
-| `rejected` | `{ reason }` recorded as async rejected |
-| `timeout` | runs the activity's real `onTimeout(pending)` (throws if undefined) |
+| Option | Type | Purpose |
+|--------|------|---------|
+| `env` | `Env.Entries` | String env vars for the run |
+| `claims` | `readonly ClaimProvider[]` | Provider implementations required by the packages the workflow calls (see each package's skill) |
+| `mockAsyncActivity` | `MockAsyncActivity` | Controls the outcome of a time-/event-based step when auto-resolution doesn't cover it |
 
-**Array** — FIFO, one entry per pending async:
+`execute()` returns the workflow output directly, then advances `env.clock` to reflect time consumed.
 
-```typescript
-mockAsyncActivity: [
-  { status: 'fulfilled', output: true },
-  { status: 'rejected', reason: false },
-]
-```
+**Replay validation is automatic.** After each `execute()`, the harness re-runs the workflow from the recorded history and from a fresh replay; a mismatch throws `NonDeterministicWorkflowError`.
 
-**Function** — `(activity, { input, pending, index }) => outcome`:
+Clock helpers:
 
 ```typescript
-mockAsyncActivity: (activity, { index }) => {
-  if (activity instanceof WaitForApprovalActivity)
-    return { status: 'fulfilled', output: true }
-  if (index === 1) return { status: 'timeout' }
-  return { status: 'rejected', reason: 'denied' }
-}
+env.clock.now()        // current pinned timestamp (ms)
+env.clock.advance(ms)  // advance the pinned clock
+env.clock.set(now)     // set the pinned clock to a Date | number
 ```
 
-Bootstrap that already returns `done`/`rejected` needs no mock. Missing mock on pending throws: `pending and no resolveAsyncActivity`. Exhausted array throws: `No more async outcomes`.
+> Wiring specific providers or controlling a specific step's outcome (e.g. an HTTP response or a `sleep` timeout) is documented in that package's skill — **framework-http**, **framework-sleep**, etc. `@t4h.framework/core/testing` exposes helpers those skills reference; you don't wire them by hand here.
 
-### Examples (from `WorkflowTesting.spec.ts`)
-
-**Sync workflow:**
-
-```typescript
-const workflow = new Workflow({ schema }, async input => {
-  const n = await History.reconciler(AddOneActivity, input.value)
-  return n * 10
-})
-await expect(WorkflowTesting.run(workflow, { value: 4 })).resolves.toBe(50)
-```
-
-**Capture logs:**
-
-```typescript
-const logs: Log[] = []
-await WorkflowTesting.run(workflow, undefined, { logs })
-expect(logs.map(entry => entry.args[0])).toEqual(['before activity', 'after activity'])
-```
-
-**Async fulfilled / rejected / timeout:**
-
-```typescript
-await WorkflowTesting.run(workflow, undefined, {
-  mockAsyncActivity: () => ({ status: 'fulfilled', output: true }),
-})
-await WorkflowTesting.run(workflow, undefined, {
-  mockAsyncActivity: () => ({ status: 'rejected', reason: false }),
-})
-await WorkflowTesting.run(workflow, undefined, {
-  mockAsyncActivity: () => ({ status: 'timeout' }),
-})
-```
-
-**Vitest setup** — add `@t4h.framework/core` and `@t4h.framework/core/testing` as devDependencies; run with Vitest (`vitest run`). See `packages/core/src/testing/__tests__/WorkflowTesting.spec.ts`.
-
-### Limits (use `Internals` instead)
-
-- No real **`advance`** — test `advance` via `Internals.runActivity` on the async class.
-- No **`PushWaitAsyncActivity`** / resuming pending `handle.wait()` across ticks.
-- Do not import `@t4h.framework/core/testing` in production app code.
+Do **not** import `@t4h.framework/core/testing` in production app code.
 
 ---
 
 ## Anti-patterns
 
-- Claims or `env` outside `Claim.run` / `Env.run`.
-- `History.reconciler` outside `History.run`.
-- Pending async tests without `mockAsyncActivity`.
-- `advance` coverage only via `WorkflowTesting` (use `Internals.runActivity`).
-- Non-`Serializable` activity I/O.
-- Duplicate `workflow.id` in `App`.
-- `@t4h.framework/core/testing` in production.
-- APIs not exported from `core.ts` / `testing/index.ts`.
+- Reading `process.env` directly, or reading the raw `env` proxy when the project should declare an `EnvDesign` in `constants/environments.ts`.
+- Inlining URLs/secrets/tenants in workflow code instead of pulling them from the shared `EnvDesign`.
+- Accessing an `EnvDesign` key at module top level (throws — no env storage outside a run); read keys inside the workflow body/functions.
+- Non-deterministic workflow bodies (`Date.now()`, `Math.random()`, ambient state) — they break replay.
+- Non-`Serializable` workflow input, output, or step values.
+- Duplicate `workflow.id` within an `App`.
+- Importing `@t4h.framework/core/testing` from production code.
+- Building low-level infrastructure inside a workflow instead of composing the framework packages that already provide it.
 
 ---
 
-## Exports (main)
+## Exports
+
+**Main (`@t4h.framework/core`):** `Workflow`, `App`, `startWorkflow`, `WorkflowRef`, `env`, `EnvDesign`, `Authorization`, `Binary`, `Serializable`.
+
+**Testing (`@t4h.framework/core/testing`):** `TestWorkflowEnvironment`, `TestClock`, `createTestEnv`, `createTestEnvEntries`, `NonDeterministicWorkflowError`.
 
-`Workflow`, `App`, `SyncActivity`, `AsyncActivity`, `Claim`, `History`, `env`, `EnvDesign`, `Authorization`, `WorkflowRef`, `Binary`, `Serializable`, async result types, `startWorkflow`, `WorkflowClaim`, `Internals`, `isActivity`, `Logger`, `Activity` types, exceptions. **Testing:** `WorkflowTesting` only.
+> Core also exports lower-level building blocks used to **author framework packages** themselves. Those are out of scope for building workflows and are not covered here — reach for the primitives above and the companion packages instead.