@wooksjs/event-core 0.7.8 → 0.7.10

package/dist/index.cjs

@@ -305,7 +305,7 @@ function resetContextInjector() {
 //#region packages/event-core/src/storage.ts
 const STORAGE_KEY = Symbol.for("wooks.core.asyncStorage");
 const VERSION_KEY = Symbol.for("wooks.core.asyncStorage.version");
-const CURRENT_VERSION = "0.7.7";
+const CURRENT_VERSION = "0.7.9";
 const _g = globalThis;
 if (_g[STORAGE_KEY]) {
 	if (_g[VERSION_KEY] !== CURRENT_VERSION) throw new Error(`[wooks] Incompatible versions of @wooksjs/event-core detected: existing v${_g[VERSION_KEY]}, loading v${CURRENT_VERSION}. All packages must use the same @wooksjs/event-core version.`);
@@ -355,19 +355,11 @@ function current() {
 function tryGetCurrent() {
 	return storage.getStore();
 }
-/**
-* Returns the logger for the current event context.
-*
-* @param ctx - Optional explicit context (defaults to `current()`)
-*
-* @example
-* ```ts
-* const logger = useLogger()
-* logger.info('Processing request')
-* ```
-*/
-function useLogger(ctx) {
-	return (ctx ?? current()).logger;
+function useLogger(topicOrCtx, maybeCtx) {
+	const ctx = (typeof topicOrCtx === "string" ? maybeCtx : topicOrCtx) ?? current();
+	const logger = ctx.logger;
+	if (typeof topicOrCtx === "string" && logger.createTopic) return logger.createTopic(topicOrCtx);
+	return logger;
 }
 function createEventContext(options, kindOrFn, seedsOrUndefined, maybeFn) {
 	const ctx = new EventContext(options);

package/dist/index.d.ts

@@ -8,8 +8,8 @@ interface Logger {
     warn(msg: string, ...args: unknown[]): void;
     error(msg: string, ...args: unknown[]): void;
     debug(msg: string, ...args: unknown[]): void;
-    /** Creates a child logger with a topic prefix (optional). */
-    topic?: (name?: string) => Logger;
+    /** Creates a child logger scoped to a topic. Matches `ProstoLogger.createTopic()`. */
+    createTopic?: (name: string) => Logger;
 }
 /**
  * A typed, writable context slot. Created with `key<T>(name)`.
@@ -405,15 +405,23 @@ declare function tryGetCurrent(): EventContext | undefined;
 /**
  * Returns the logger for the current event context.
  *
- * @param ctx - Optional explicit context (defaults to `current()`)
+ * When called with a `topic` string, creates a child logger via
+ * `logger.createTopic()` (if supported). Falls back to the base
+ * logger when `createTopic` is not available.
  *
  * @example
  * ```ts
  * const logger = useLogger()
  * logger.info('Processing request')
+ *
+ * const scoped = useLogger('auth')
+ * scoped.warn('Token expired')
  * ```
  */
-declare function useLogger(ctx?: EventContext): Logger;
+declare function useLogger(): Logger;
+declare function useLogger(topic: string): Logger;
+declare function useLogger(ctx: EventContext): Logger;
+declare function useLogger(topic: string, ctx: EventContext): Logger;
 /**
  * Creates a new `EventContext`, makes it the active context via
  * `AsyncLocalStorage`, and runs `fn` inside it.

package/dist/index.mjs

@@ -282,7 +282,7 @@ function resetContextInjector() {
 //#region packages/event-core/src/storage.ts
 const STORAGE_KEY = Symbol.for("wooks.core.asyncStorage");
 const VERSION_KEY = Symbol.for("wooks.core.asyncStorage.version");
-const CURRENT_VERSION = "0.7.7";
+const CURRENT_VERSION = "0.7.9";
 const _g = globalThis;
 if (_g[STORAGE_KEY]) {
 	if (_g[VERSION_KEY] !== CURRENT_VERSION) throw new Error(`[wooks] Incompatible versions of @wooksjs/event-core detected: existing v${_g[VERSION_KEY]}, loading v${CURRENT_VERSION}. All packages must use the same @wooksjs/event-core version.`);
@@ -332,19 +332,11 @@ function current() {
 function tryGetCurrent() {
 	return storage.getStore();
 }
-/**
-* Returns the logger for the current event context.
-*
-* @param ctx - Optional explicit context (defaults to `current()`)
-*
-* @example
-* ```ts
-* const logger = useLogger()
-* logger.info('Processing request')
-* ```
-*/
-function useLogger(ctx) {
-	return (ctx ?? current()).logger;
+function useLogger(topicOrCtx, maybeCtx) {
+	const ctx = (typeof topicOrCtx === "string" ? maybeCtx : topicOrCtx) ?? current();
+	const logger = ctx.logger;
+	if (typeof topicOrCtx === "string" && logger.createTopic) return logger.createTopic(topicOrCtx);
+	return logger;
 }
 function createEventContext(options, kindOrFn, seedsOrUndefined, maybeFn) {
 	const ctx = new EventContext(options);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wooksjs/event-core",
-  "version": "0.7.8",
+  "version": "0.7.10",
   "description": "@wooksjs/event-core",
   "keywords": [
     "composables",
@@ -20,13 +20,8 @@
     "url": "git+https://github.com/wooksjs/wooksjs.git",
     "directory": "packages/event-core"
   },
-  "bin": {
-    "wooksjs-event-core-skill": "./scripts/setup-skills.js"
-  },
   "files": [
-    "dist",
-    "skills",
-    "scripts/setup-skills.js"
+    "dist"
   ],
   "main": "dist/index.cjs",
   "module": "dist/index.mjs",
@@ -44,7 +39,6 @@
     "vitest": "^3.2.4"
   },
   "scripts": {
-    "build": "rolldown -c ../../rolldown.config.mjs",
-    "setup-skills": "node ./scripts/setup-skills.js"
+    "build": "rolldown -c ../../rolldown.config.mjs"
   }
 }

package/scripts/setup-skills.js

@@ -1,78 +0,0 @@
-#!/usr/bin/env node
-/* prettier-ignore */
-import fs from 'fs'
-import path from 'path'
-import os from 'os'
-import { fileURLToPath } from 'url'
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url))
-
-const SKILL_NAME = 'wooksjs-event-core'
-const SKILL_SRC = path.join(__dirname, '..', 'skills', SKILL_NAME)
-
-if (!fs.existsSync(SKILL_SRC)) {
-  console.error(`No skills found at ${SKILL_SRC}`)
-  console.error('Add your SKILL.md files to the skills/' + SKILL_NAME + '/ directory first.')
-  process.exit(1)
-}
-
-const AGENTS = {
-  'Claude Code': { dir: '.claude/skills',   global: path.join(os.homedir(), '.claude', 'skills') },
-  'Cursor':      { dir: '.cursor/skills',   global: path.join(os.homedir(), '.cursor', 'skills') },
-  'Windsurf':    { dir: '.windsurf/skills', global: path.join(os.homedir(), '.windsurf', 'skills') },
-  'Codex':       { dir: '.codex/skills',    global: path.join(os.homedir(), '.codex', 'skills') },
-  'OpenCode':    { dir: '.opencode/skills', global: path.join(os.homedir(), '.opencode', 'skills') },
-}
-
-const args = process.argv.slice(2)
-const isGlobal = args.includes('--global') || args.includes('-g')
-const isPostinstall = args.includes('--postinstall')
-let installed = 0, skipped = 0
-const installedDirs = []
-
-for (const [agentName, cfg] of Object.entries(AGENTS)) {
-  const targetBase = isGlobal ? cfg.global : path.join(process.cwd(), cfg.dir)
-  const agentRootDir = path.dirname(cfg.global) // Check if the agent has ever been installed globally
-
-  // In postinstall mode: silently skip agents that aren't set up globally
-  if (isPostinstall || isGlobal) {
-    if (!fs.existsSync(agentRootDir)) { skipped++; continue }
-  }
-
-  const dest = path.join(targetBase, SKILL_NAME)
-  try {
-    fs.mkdirSync(dest, { recursive: true })
-    fs.cpSync(SKILL_SRC, dest, { recursive: true })
-    console.log(`✅  ${agentName}: installed to ${dest}`)
-    installed++
-    if (!isGlobal) installedDirs.push(cfg.dir + '/' + SKILL_NAME)
-  } catch (err) {
-    console.warn(`⚠️   ${agentName}: failed — ${err.message}`)
-  }
-}
-
-// Add locally-installed skill dirs to .gitignore
-if (!isGlobal && installedDirs.length > 0) {
-  const gitignorePath = path.join(process.cwd(), '.gitignore')
-  let gitignoreContent = ''
-  try { gitignoreContent = fs.readFileSync(gitignorePath, 'utf8') } catch {}
-  const linesToAdd = installedDirs.filter(d => !gitignoreContent.includes(d))
-  if (linesToAdd.length > 0) {
-    const hasHeader = gitignoreContent.includes('# AI agent skills')
-    const block = (gitignoreContent && !gitignoreContent.endsWith('\n') ? '\n' : '')
-      + (hasHeader ? '' : '\n# AI agent skills (auto-generated by setup-skills)\n')
-      + linesToAdd.join('\n') + '\n'
-    fs.appendFileSync(gitignorePath, block)
-    console.log(`📝  Added ${linesToAdd.length} entries to .gitignore`)
-  }
-}
-
-if (installed === 0 && isPostinstall) {
-  // Silence is fine — no agents present, nothing to do
-} else if (installed === 0 && skipped === Object.keys(AGENTS).length) {
-  console.log('No agent directories detected. Try --global or run without it for project-local install.')
-} else if (installed === 0) {
-  console.log('Nothing installed. Run without --global to install project-locally.')
-} else {
-  console.log(`\n✨  Done! Restart your AI agent to pick up the "${SKILL_NAME}" skill.`)
-}

package/skills/wooksjs-event-core/SKILL.md

@@ -1,51 +0,0 @@
----
-name: wooksjs-event-core
-description: Use this skill when working with @wooksjs/event-core — to create typed context slots with key(), build lazy cached computations with cached() and cachedBy(), define composables with defineWook(), define event kind schemas with defineEventKind() and slot(), manage EventContext lifecycle with run()/current()/createEventContext(), or build custom Wooks adapters. Covers useLogger(), useRouteParams(), useEventId(), and AsyncLocalStorage-based context propagation.
----
-
-# @wooksjs/event-core
-
-Typed, per-event context with lazy cached computations, composable API (`defineWook`), and `AsyncLocalStorage` propagation. The foundation layer for all `@wooksjs` adapters (HTTP, CLI, workflows).
-
-## How to use this skill
-
-Read the domain file that matches the task. Do not load all files — only what you need.
-
-| Domain                | File                             | Load when...                                                                                                              |
-| --------------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
-| Core concepts & setup | [core.md](core.md)               | Starting a new project, understanding the mental model, seeing all exports                                                |
-| Primitives            | [primitives.md](primitives.md)   | Creating typed slots (`key`), lazy computations (`cached`, `cachedBy`), or event kind schemas (`slot`, `defineEventKind`) |
-| Composables           | [composables.md](composables.md) | Building custom composables with `defineWook`, using built-in composables (`useRouteParams`, `useEventId`, `useLogger`)   |
-| Context & runtime     | [context.md](context.md)         | Managing `EventContext` lifecycle, `run`/`current`/`createEventContext`, async propagation, performance optimization      |
-
-## Quick reference
-
-```ts
-import {
-  // primitives
-  key,
-  cached,
-  cachedBy,
-  slot,
-  defineEventKind,
-  defineWook,
-  // context
-  EventContext,
-  run,
-  current,
-  tryGetCurrent,
-  createEventContext,
-  // composables
-  useRouteParams,
-  useEventId,
-  useLogger,
-  // standard keys
-  routeParamsKey,
-  eventTypeKey,
-  // observability
-  ContextInjector,
-  getContextInjector,
-  replaceContextInjector,
-  resetContextInjector,
-} from '@wooksjs/event-core'
-```

package/skills/wooksjs-event-core/composables.md

@@ -1,200 +0,0 @@
-# Composables — @wooksjs/event-core
-
-> `defineWook` and the built-in composables: `useRouteParams`, `useEventId`, `useLogger`.
-
-## Concepts
-
-A **composable** is a function that accesses per-event contextual data. Call it — get typed data back. No arguments needed (context resolved via `AsyncLocalStorage`).
-
-`defineWook(factory)` is the primitive that creates composables. The factory runs once per `EventContext`, and the result is cached. Every subsequent call within the same event returns the same object.
-
-All built-in composables across the Wooks ecosystem (`useRequest`, `useResponse`, `useBody`, `useCookies`, etc.) are built with `defineWook`.
-
-## API Reference
-
-### `defineWook<T>(factory: (ctx: EventContext) => T): (ctx?: EventContext) => T`
-
-Creates a composable with per-event caching. Internally wraps the factory in a `cached()` slot.
-
-```ts
-import { defineWook, defineEventKind, slot } from '@wooksjs/event-core'
-
-const http = defineEventKind('http', {
-  method: slot<string>(),
-  path: slot<string>(),
-})
-
-const useRequest = defineWook((ctx) => ({
-  method: ctx.get(http.keys.method),
-  path: ctx.get(http.keys.path),
-}))
-
-// In a handler:
-const { method, path } = useRequest()
-```
-
-**Caching guarantee:** The factory runs exactly once per event context. Subsequent calls return the same object:
-
-```ts
-const a = useRequest()
-const b = useRequest()
-a === b // true — same object reference
-```
-
-**Optional explicit context:** Pass `ctx` to skip the `AsyncLocalStorage` lookup:
-
-```ts
-const ctx = current()
-const { method } = useRequest(ctx)
-const { parseBody } = useBody(ctx)
-```
-
-### `useRouteParams<T>(ctx?): { params: T; get: (name) => T[K] }`
-
-Returns route parameters set by the router. Generic `T` defaults to `Record<string, string | string[]>`.
-
-```ts
-import { useRouteParams } from '@wooksjs/event-core'
-
-// Given route /users/:id
-const { params, get } = useRouteParams<{ id: string }>()
-params.id // 'abc'
-get('id') // 'abc'
-```
-
-### `useEventId(ctx?): { getId: () => string }`
-
-Returns a lazy UUID for the current event. The UUID is generated on first call to `getId()` and cached.
-
-```ts
-import { useEventId } from '@wooksjs/event-core'
-
-const { getId } = useEventId()
-getId() // 'a1b2c3d4-...' (stable for this event)
-```
-
-### `useLogger(ctx?): Logger`
-
-Returns the logger from the current event context. Shorthand for `(ctx ?? current()).logger`.
-
-```ts
-import { useLogger } from '@wooksjs/event-core'
-
-const log = useLogger()
-log.info('handling request')
-```
-
-## Common Patterns
-
-### Pattern: Composable with lazy properties
-
-Wrap non-trivial computations in thunks so they only run when accessed:
-
-```ts
-const useRequest = defineWook((ctx) => ({
-  method: ctx.get(http.keys.method), // cheap — direct key lookup
-  query: () => ctx.get(parsedQuery), // deferred until called
-  cookies: () => ctx.get(parsedCookies), // deferred until called
-}))
-
-// Only method is computed eagerly:
-const { method } = useRequest()
-// query is only computed if accessed:
-const q = useRequest().query()
-```
-
-### Pattern: Composable with async cached values
-
-Combine `defineWook` with `cached` for async computations:
-
-```ts
-const parsedBody = cached(async (ctx) => {
-  const buf = await ctx.get(rawBody)
-  return JSON.parse(buf.toString())
-})
-
-const useBody = defineWook((ctx) => ({
-  parseBody: () => ctx.get(parsedBody),
-}))
-
-// In handler:
-const { parseBody } = useBody()
-const body = await parseBody() // parses once
-const again = await parseBody() // cache hit, same object
-```
-
-### Pattern: Class-based composable for method-heavy APIs
-
-When a composable exposes many methods, use a class to avoid per-event closure allocation:
-
-```ts
-class ResponseState {
-  status = 200
-  body: unknown = undefined
-  readonly headers = new Map<string, string>()
-
-  setHeader(name: string, value: string) {
-    this.headers.set(name, value)
-    return this
-  }
-  setStatus(code: number) {
-    this.status = code
-    return this
-  }
-  json(data: unknown) {
-    this.body = data
-    return this
-  }
-}
-
-const useResponse = defineWook(() => new ResponseState())
-```
-
-Methods live on the prototype — zero closures per event.
-
-### Pattern: Composable depending on another composable
-
-Composables can call other composables inside their factory:
-
-```ts
-const useCurrentUser = defineWook((ctx) => {
-  const { basicCredentials } = useAuthorization(ctx)
-  const username = basicCredentials()?.username
-  return {
-    username,
-    profile: async () => (username ? await db.findUser(username) : null),
-  }
-})
-```
-
-Pass `ctx` to avoid redundant `AsyncLocalStorage` lookups.
-
-### Pattern: Plain function for single-value access
-
-`defineWook` adds caching overhead. For trivial single-value access, use a plain function:
-
-```ts
-// Overkill — caching overhead > value cost
-const useMethod = defineWook((ctx) => ctx.get(http.keys.method))
-
-// Better — one Map.get, no caching layer
-function useMethod(ctx?: EventContext): string {
-  return (ctx ?? current()).get(http.keys.method) ?? 'GET'
-}
-```
-
-## Best Practices
-
-- Use `defineWook` when the factory returns an object with multiple properties or methods
-- Use plain functions for trivial single-value access
-- Always accept optional `ctx` parameter in composables for performance
-- Pass `ctx` explicitly when calling multiple composables in sequence
-- Use thunks for non-trivial properties in the returned object
-- Use classes for composables with 4+ methods
-
-## Gotchas
-
-- `defineWook` factory receives `ctx` as parameter — use it instead of calling `current()` inside
-- The factory runs once per context — don't put per-call logic in it (use thunks for that)
-- Calling a composable outside an event context throws `No active event context`
-- Different event contexts get different composable instances — the cache is per-context

package/skills/wooksjs-event-core/context.md

@@ -1,288 +0,0 @@
-# Context & runtime — @wooksjs/event-core
-
-> `EventContext` class, `run`/`current`/`createEventContext`, async propagation, and performance.
-
-## Concepts
-
-Every event in Wooks gets its own `EventContext` — a lightweight container backed by `Map<number, unknown>`. The context is propagated through the async call stack via Node.js `AsyncLocalStorage`.
-
-The lifecycle:
-
-1. Create an `EventContext` (or use `createEventContext`), optionally linking a `parent` context
-2. Seed it with event-specific data via `ctx.seed(kind, seeds)`
-3. Enter the `AsyncLocalStorage` scope with `run(ctx, fn)`
-4. Inside `fn`, composables resolve the context via `current()`
-
-Adapters (HTTP, CLI, etc.) handle steps 1-3. Your handler code only interacts with composables.
-
-## API Reference
-
-### `EventContext`
-
-```ts
-import { EventContext } from '@wooksjs/event-core'
-
-const ctx = new EventContext({ logger })
-```
-
-**Constructor options:**
-
-```ts
-interface EventContextOptions {
-  logger: Logger
-  parent?: EventContext
-}
-```
-
-Every context requires a `Logger`. Access it via `ctx.logger`.
-
-When `parent` is provided, the child context forms a **parent chain**. Lookups via `get()`, `set()`, and `has()` traverse the chain (local first, then parent, then grandparent, etc.). This replaces the old pattern of attaching multiple kinds to a single context — instead, create child contexts with parent links:
-
-```ts
-const parentCtx = new EventContext({ logger })
-parentCtx.seed(httpKind, { method: 'GET', path: '/api' })
-
-const childCtx = new EventContext({ logger, parent: parentCtx })
-childCtx.seed(workflowKind, { triggerId: 'deploy-42' })
-
-// child can see its own data AND parent data
-childCtx.get(httpKind.keys.method) // 'GET' (found in parent)
-childCtx.get(workflowKind.keys.triggerId) // 'deploy-42' (found locally)
-```
-
-**Methods:**
-
-#### `ctx.get<T>(accessor: Key<T> | Cached<T>): T`
-
-Get a value by key or cached accessor. **Traverses the parent chain:** checks local context first, then parent, grandparent, and so on.
-
-- For `Key<T>`: returns the first value found in the chain. Throws `Key "name" is not set` if not found in any context.
-- For `Cached<T>`: if a computed value is found anywhere in the parent chain, returns it (no re-computation). If not found in any context, computes and caches the result **locally**.
-
-#### `ctx.set<T>(key: Key<T> | Cached<T>, value: T): void`
-
-Set a value for a key. **Traverses the parent chain:** if the key already exists somewhere in the chain, writes to that context. If the key is new (not found in any ancestor), writes locally. Works with `undefined`, `null`, and falsy values.
-
-#### `ctx.has(accessor: Accessor<any>): boolean`
-
-Check if a slot has been set or computed. **Traverses the parent chain.** Returns `true` if the slot is found in any context in the chain. Returns `false` for unset keys and uncomputed cached values across the entire chain.
-
-#### `ctx.getOwn<T>(accessor: Key<T> | Cached<T>): T`
-
-Like `get()`, but **local only** — does not traverse the parent chain. Returns the value from this context only. Throws if not set locally.
-
-#### `ctx.setOwn<T>(key: Key<T> | Cached<T>, value: T): void`
-
-Like `set()`, but **local only** — always writes to this context, even if the key exists in a parent.
-
-#### `ctx.hasOwn(accessor: Accessor<any>): boolean`
-
-Like `has()`, but **local only** — returns `true` only if the slot is set in this context, ignoring parents.
-
-#### `ctx.seed(kind, seeds[, fn])`
-
-Populate context from an `EventKind` schema (previously called `attach`):
-
-```ts
-const http = defineEventKind('http', {
-  method: slot<string>(),
-  path: slot<string>(),
-})
-
-ctx.seed(http, { method: 'GET', path: '/api' })
-ctx.get(http.keys.method) // 'GET'
-```
-
-Also sets `eventTypeKey` to the kind's name.
-
-Overloaded: can accept an optional callback that runs immediately after seeding:
-
-```ts
-ctx.seed(http, seeds, () => {
-  // seeds are available here
-})
-```
-
-### `run<R>(ctx: EventContext, fn: () => R): R`
-
-Execute `fn` within the `AsyncLocalStorage` scope of `ctx`. Returns the fn's return value. Works with async functions.
-
-```ts
-const ctx = new EventContext({ logger })
-const result = run(ctx, () => {
-  // current() returns ctx here
-  return 'hello'
-})
-// result === 'hello'
-```
-
-Supports nesting — inner `run` creates a child scope:
-
-```ts
-run(outer, () => {
-  current() === outer // true
-  run(inner, () => {
-    current() === inner // true
-  })
-  current() === outer // true (restored)
-})
-```
-
-### `current(): EventContext`
-
-Get the active `EventContext` from the `AsyncLocalStorage` scope. Throws `[Wooks] No active event context` if called outside a `run` scope.
-
-### `tryGetCurrent(): EventContext | undefined`
-
-Like `current()` but returns `undefined` instead of throwing.
-
-### `createEventContext(options, fn): R`
-
-### `createEventContext(options, kind, seeds, fn): R`
-
-Convenience: creates a context, optionally seeds a kind, and runs `fn` inside `AsyncLocalStorage`:
-
-```ts
-// Bare context
-createEventContext({ logger }, () => {
-  const ctx = current()
-  // ...
-})
-
-// With kind + seeds
-createEventContext({ logger }, httpKind, { method: 'GET', path: '/' }, () => {
-  current().get(httpKind.keys.method) // 'GET'
-})
-```
-
-Returns the fn's return value. Works with async callbacks.
-
-### `useLogger(ctx?: EventContext): Logger`
-
-Shorthand for `(ctx ?? current()).logger`.
-
-## Version safety
-
-`@wooksjs/event-core` uses a global `Symbol.for('wooks.core.asyncStorage')` to ensure a single `AsyncLocalStorage` instance across the process. If two incompatible versions are loaded, it throws at import time:
-
-```
-[wooks] Incompatible versions of @wooksjs/event-core detected: existing v0.6.6, loading v0.7.0
-```
-
-This prevents subtle bugs from multiple context stores.
-
-## Common Patterns
-
-### Pattern: Custom adapter
-
-Build an adapter that creates contexts and runs handlers. Each adapter exports a **context factory** that hardcodes the kind and delegates to `createEventContext`:
-
-```ts
-import { createEventContext, defineEventKind, slot } from '@wooksjs/event-core'
-import type { EventContextOptions, EventKindSeeds } from '@wooksjs/event-core'
-
-const myKind = defineEventKind('my-event', {
-  data: slot<unknown>(),
-})
-
-// Context factory — same signature as createEventContext, minus the kind
-export function createMyEventContext<R>(
-  options: EventContextOptions,
-  seeds: EventKindSeeds<typeof myKind>,
-  fn: () => R,
-): R {
-  return createEventContext(options, myKind, seeds, fn)
-}
-
-// Usage in the adapter
-function handleEvent(data: unknown, handler: () => unknown) {
-  return createMyEventContext({ logger: console }, { data }, handler)
-}
-```
-
-All built-in adapters follow this pattern: `createHttpContext`, `createCliContext`, `createWsConnectionContext`, `createWsMessageContext`, `createWfContext`, `resumeWfContext`.
-
-### Pattern: Child contexts with parent links
-
-Instead of attaching multiple kinds to a single context, create child contexts by passing `parent` in the options. Each child sees its own data plus everything in the parent chain:
-
-```ts
-createEventContext({ logger }, httpKind, httpSeeds, () => {
-  const parentCtx = current()
-
-  // Create a child context linked to the HTTP parent
-  createEventContext(
-    { logger, parent: parentCtx },
-    workflowKind,
-    { triggerId: 'deploy-42', payload },
-    () => {
-      // Both HTTP and workflow composables work
-      const { method } = useRequest() // found via parent chain
-      const { triggerId } = useWorkflow() // found locally
-    },
-  )
-})
-```
-
-The parent chain allows layered contexts — for example, a base HTTP context can be shared across sub-handlers, each with their own child context carrying handler-specific state.
-
-### Pattern: Resolve context once for hot paths
-
-Each composable call without `ctx` hits `AsyncLocalStorage.getStore()`. For hot paths:
-
-```ts
-// 4 ALS lookups
-const { method } = useRequest()
-const { parseBody } = useBody()
-const session = getCookie('session')
-const log = useLogger()
-
-// 1 ALS lookup
-const ctx = current()
-const { method } = useRequest(ctx)
-const { parseBody } = useBody(ctx)
-const session = getCookie('session', ctx)
-const log = ctx.logger
-```
-
-## ContextInjector (observability)
-
-`ContextInjector` is a hook point for observability tools (OpenTelemetry, etc.). No injector is installed by default — `getContextInjector()` returns `null`, so all adapters run with zero overhead until one is installed.
-
-```ts
-import { ContextInjector, replaceContextInjector, resetContextInjector } from '@wooksjs/event-core'
-
-class OtelInjector extends ContextInjector<string> {
-  with<T>(name: string, attributes: Record<string, any>, cb: () => T): T {
-    return tracer.startActiveSpan(name, { attributes }, () => cb())
-  }
-}
-
-replaceContextInjector(new OtelInjector())
-
-// To disable instrumentation later:
-resetContextInjector()
-```
-
-The injector's `with()` method wraps `createEventContext` callbacks. All adapters (HTTP, CLI, WS, WF) route through `createEventContext`, so installing an injector automatically instruments every event type.
-
-Adapter callbacks **return their result** (sync value or Promise), so `with()` can track async handler completion for span lifecycle. A `TracingInjector` can detect thenable returns and attach `.then()/.catch()` to end spans when the handler settles — no separate `onEnd()` hook needed.
-
-## Best Practices
-
-- Let adapters handle context creation — in handler code, just use composables
-- Pass `ctx` explicitly in hot paths with multiple composable calls
-- Use `tryGetCurrent()` in library code that may run outside event scope
-- Keep `Logger` simple — the interface is `info/warn/error/debug` with optional `topic()`
-- Prefer parent-linked child contexts over seeding multiple kinds into one context — the parent chain keeps each layer's data isolated while still accessible
-- Use `getOwn()`/`setOwn()`/`hasOwn()` when you need to guarantee local-only access and avoid unintended reads from or writes to parent contexts
-
-## Gotchas
-
-- `current()` throws outside `run()` scope — use `tryGetCurrent()` if that's expected
-- `AsyncLocalStorage` propagates through `await`, `setTimeout`, `setImmediate`, and Promise chains
-- `EventContext` is not thread-safe — it's designed for single-event, single-async-chain use
-- The global singleton `AsyncLocalStorage` means all `@wooksjs/event-core` consumers in a process share context — version mismatches are caught at import time
-- `set()` writes to the first context in the parent chain where the key exists — if you need to shadow a parent value locally, use `setOwn()`
-- `get()` on a `Cached<T>` found in a parent returns the parent's cached value without re-computing — if you need a fresh local computation, use `getOwn()`
-- Parent chain traversal has O(depth) cost per lookup — keep chains shallow for performance

package/skills/wooksjs-event-core/core.md

@@ -1,92 +0,0 @@
-# Core concepts & setup — @wooksjs/event-core
-
-> Package overview, mental model, installation, and exports map.
-
-## What it is
-
-`@wooksjs/event-core` is the context engine underneath all Wooks adapters. It provides:
-
-- **Typed slots** (`key<T>`) — explicit get/set per event
-- **Lazy cached computations** (`cached`, `cachedBy`) — compute once, cache for event lifetime
-- **Event kind schemas** (`defineEventKind`) — typed seed bundles for domain-specific data
-- **Composable factories** (`defineWook`) — per-event cached functions, resolved via `AsyncLocalStorage`
-- **Async propagation** (`run`, `current`) — context available anywhere in the call stack
-
-## Installation
-
-```bash
-pnpm add @wooksjs/event-core
-```
-
-Typically you don't install this directly — it's a dependency of `@wooksjs/event-http`, `@wooksjs/event-cli`, etc. Install it when building custom adapters or composables that don't depend on a specific event type.
-
-## Mental model
-
-```
-EventContext = Map<number, unknown>  (flat, typed via key/cached accessors)
-    │
-    ├── key<T>(name)         → writable slot, explicit set/get
-    ├── cached<T>(fn)        → read-only slot, lazy, computed on first access
-    ├── cachedBy<K,V>(fn)    → like cached but keyed — one result per unique argument
-    │
-    ├── defineEventKind(name, schema)  → groups slots into a named seed bundle
-    │       └── ctx.seed(kind, seeds)  → populates slots from seeds
-    │
-    ├── defineWook(factory)  → creates a composable: factory runs once per context, cached
-    │       └── useX()       → resolves from AsyncLocalStorage, returns cached result
-    │
-    └── parent chain         → optional parent: EventContext link
-            ├── get/set/has  → traverse local → parent → grandparent → ...
-            └── getOwn/setOwn/hasOwn → local-only (no traversal)
-```
-
-Every event (HTTP request, CLI invocation, workflow step) gets its own `EventContext`. The context is propagated via `AsyncLocalStorage` — composables resolve it implicitly.
-
-## Exports
-
-| Export                                        | Kind       | Purpose                                                                                                          |
-| --------------------------------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------- |
-| `key<T>(name)`                                | primitive  | Writable typed slot                                                                                              |
-| `cached<T>(fn)`                               | primitive  | Lazy computed slot, cached per event                                                                             |
-| `cachedBy<K,V>(fn)`                           | primitive  | Lazy computed slot, cached per key per event                                                                     |
-| `slot<T>()`                                   | primitive  | Type marker for `defineEventKind` schemas                                                                        |
-| `defineEventKind(name, schema)`               | primitive  | Typed seed bundle definition                                                                                     |
-| `defineWook<T>(factory)`                      | primitive  | Composable factory with per-event caching                                                                        |
-| `EventContext`                                | class      | Per-event context container (`get`, `set`, `has`, `seed`, `getOwn`, `setOwn`, `hasOwn`; optional `parent` chain) |
-| `run(ctx, fn)`                                | function   | Execute `fn` within `ctx` via `AsyncLocalStorage`                                                                |
-| `current()`                                   | function   | Get active `EventContext` (throws if none)                                                                       |
-| `tryGetCurrent()`                             | function   | Get active `EventContext` or `undefined`                                                                         |
-| `createEventContext(opts, [kind, seeds,] fn)` | function   | Create context (with optional parent) + optional seed + run                                                      |
-| `useLogger(ctx?)`                             | composable | Shorthand for `(ctx ?? current()).logger`                                                                        |
-| `useRouteParams(ctx?)`                        | composable | Route parameters from router                                                                                     |
-| `useEventId(ctx?)`                            | composable | Lazy UUID per event                                                                                              |
-| `routeParamsKey`                              | key        | Standard key for route params                                                                                    |
-| `eventTypeKey`                                | key        | Standard key for event type name                                                                                 |
-| `ContextInjector`                             | class      | Observability hook point (OpenTelemetry etc.). Defaults to `null` — zero overhead until installed.               |
-| `getContextInjector()`                        | function   | Get current injector (returns `null` when none installed)                                                        |
-| `replaceContextInjector(ci)`                  | function   | Install a custom injector (e.g. with OTel spans)                                                                 |
-| `resetContextInjector()`                      | function   | Reset injector back to `null` (disables instrumentation)                                                         |
-
-## Types
-
-```ts
-interface Logger {
-  info(msg: string, ...args: unknown[]): void
-  warn(msg: string, ...args: unknown[]): void
-  error(msg: string, ...args: unknown[]): void
-  debug(msg: string, ...args: unknown[]): void
-  topic?: (name?: string) => Logger
-}
-
-interface Key<T> { readonly _id: number; readonly _name: string }
-interface Cached<T> { readonly _id: number; readonly _name: string; readonly _fn: (ctx: EventContext) => T }
-type Accessor<T> = Key<T> | Cached<T>
-interface SlotMarker<T> {}  // phantom type marker
-
-type EventKind<S extends Record<string, SlotMarker<any>>> = {
-  readonly name: string
-  readonly keys: { [K in keyof S]: S[K] extends SlotMarker<infer V> ? Key<V> : never }
-  readonly _entries: Array<[string, Key<unknown>]> // internal, used by ctx.seed()
-}
-type EventKindSeeds<K> = // maps SlotMarker<V> → V for each property
-```

package/skills/wooksjs-event-core/primitives.md

@@ -1,213 +0,0 @@
-# Primitives — @wooksjs/event-core
-
-> `key`, `cached`, `cachedBy`, `slot`, `defineEventKind` — the building blocks for typed per-event state.
-
-## Concepts
-
-All state lives in `EventContext` — a flat `Map<number, unknown>`. Primitives give you typed accessors into that map:
-
-- **`key<T>`** — a writable slot. You `set` and `get` values explicitly.
-- **`cached<T>`** — a read-only slot. Computed lazily on first `get`, cached for the event lifetime.
-- **`cachedBy<K,V>`** — like `cached`, but parameterized. One cached result per unique key.
-- **`slot<T>`** / **`defineEventKind`** — group multiple keys into a typed seed bundle that can be seeded into a context in one call.
-
-All primitives are defined at module level (not per request). They produce lightweight descriptors with auto-incremented numeric IDs.
-
-## API Reference
-
-### `key<T>(name: string): Key<T>`
-
-Creates a writable typed slot. The `name` is for debugging only — lookup is by numeric ID.
-
-```ts
-import { key, EventContext } from '@wooksjs/event-core'
-
-const userId = key<string>('userId')
-
-const ctx = new EventContext({ logger })
-ctx.set(userId, 'u-123')
-ctx.get(userId) // 'u-123' (typed as string)
-```
-
-Throws `Key "name" is not set` if `get` is called before `set`.
-
-Supports `undefined`, `null`, `0`, `''`, `false` — all falsy values are stored correctly.
-
-### `cached<T>(fn: (ctx: EventContext) => T): Cached<T>`
-
-Creates a lazy computed slot. The function runs on first `ctx.get()` and the result is cached.
-
-```ts
-import { cached, key } from '@wooksjs/event-core'
-
-const url = key<string>('url')
-const parsedQuery = cached((ctx) => {
-  return Object.fromEntries(new URL(ctx.get(url)).searchParams)
-})
-
-// First access: computes and caches
-ctx.get(parsedQuery)
-// Second access: returns cached result, fn never runs again
-ctx.get(parsedQuery)
-```
-
-**Async:** The Promise itself is cached — concurrent access deduplicates:
-
-```ts
-const rawBody = cached(async (ctx) => {
-  const chunks: Buffer[] = []
-  for await (const chunk of ctx.get(reqStream)) chunks.push(chunk)
-  return Buffer.concat(chunks)
-})
-
-// Two concurrent calls → one stream read, one Promise
-const [a, b] = await Promise.all([ctx.get(rawBody), ctx.get(rawBody)])
-a === b // true
-```
-
-**Errors** are cached too — a failed computation throws the same error on subsequent access without re-executing.
-
-**Circular dependencies** are detected and throw immediately: `Circular dependency detected for "name"`.
-
-### `cachedBy<K, V>(fn: (key: K, ctx: EventContext) => V): (key: K, ctx?: EventContext) => V`
-
-Like `cached`, but parameterized. Maintains a `Map<K, V>` per context — each unique key computes once.
-
-```ts
-import { cachedBy } from '@wooksjs/event-core'
-
-const getCookie = cachedBy((name: string, ctx) => {
-  const header = ctx.get(rawHeaders)['cookie'] ?? ''
-  const match = header.match(new RegExp(`(?:^|;\\s*)${name}=([^;]*)`))
-  return match?.[1]
-})
-
-getCookie('session') // extracts + caches
-getCookie('session') // cache hit
-getCookie('theme') // extracts + caches (different key)
-```
-
-The returned function accepts an optional `ctx` parameter to skip `AsyncLocalStorage` lookup:
-
-```ts
-const ctx = current()
-getCookie('session', ctx) // explicit context, no ALS overhead
-```
-
-### `slot<T>(): SlotMarker<T>`
-
-A phantom type marker used in `defineEventKind` schemas. Has no runtime behavior — it only carries the type `T`.
-
-```ts
-import { slot } from '@wooksjs/event-core'
-
-const schema = {
-  method: slot<string>(),
-  path: slot<string>(),
-  req: slot<IncomingMessage>(),
-}
-```
-
-### `defineEventKind<S>(name: string, schema: S): EventKind<S>`
-
-Groups slots into a named kind. Creates a `Key<T>` for each slot in the schema, namespaced under the kind name.
-
-```ts
-import { defineEventKind, slot } from '@wooksjs/event-core'
-
-const httpKind = defineEventKind('http', {
-  method: slot<string>(),
-  path: slot<string>(),
-  rawHeaders: slot<Record<string, string>>(),
-})
-
-// httpKind.name === 'http'
-// httpKind.keys.method is Key<string> with _name 'http.method'
-// httpKind.keys.path is Key<string> with _name 'http.path'
-```
-
-Seed into a context with `ctx.seed()`:
-
-```ts
-ctx.seed(httpKind, {
-  method: 'POST',
-  path: '/api/users',
-  rawHeaders: { 'content-type': 'application/json' },
-})
-
-ctx.get(httpKind.keys.method) // 'POST'
-```
-
-Multiple kinds can be layered via **parent-linked contexts** instead of seeding everything into one context:
-
-```ts
-const parentCtx = new EventContext({ logger })
-parentCtx.seed(httpKind, { method: 'POST', path: '/webhook', rawHeaders: {} })
-
-const childCtx = new EventContext({ logger, parent: parentCtx })
-childCtx.seed(workflowKind, { triggerId: 'deploy-42', payload: { env: 'prod' } })
-
-// Child sees both its own and parent data via the parent chain
-childCtx.get(httpKind.keys.method) // 'POST' (from parent)
-childCtx.get(workflowKind.keys.triggerId) // 'deploy-42' (local)
-```
-
-## Common Patterns
-
-### Pattern: Derived computation chain
-
-Cached values can depend on keys and on other cached values. The dependency graph is resolved lazily.
-
-```ts
-const base = key<number>('base')
-const doubled = cached((ctx) => ctx.get(base) * 2)
-const quadrupled = cached((ctx) => ctx.get(doubled) * 2)
-
-ctx.set(base, 5)
-ctx.get(quadrupled) // 20 — computes doubled (10) then quadrupled (20)
-```
-
-### Pattern: Library extension via cached slots
-
-Libraries export `cached` slots for other libraries to depend on:
-
-```ts
-// http-context library
-export const rawBody = cached(async (ctx) => readStream(ctx.get(httpKind.keys.req)))
-
-// body-parser library (depends on http-context)
-import { rawBody } from 'http-context'
-
-const parsedBody = cached(async (ctx) => {
-  const buf = await ctx.get(rawBody)
-  return JSON.parse(buf.toString())
-})
-```
-
-### Pattern: Sparse access with cachedBy
-
-When the data source is large but your app reads few entries:
-
-```ts
-// Parses only requested cookies, not all 40
-const getCookie = cachedBy((name: string, ctx) => {
-  const header = ctx.get(rawHeaders)['cookie'] ?? ''
-  const match = header.match(new RegExp(`(?:^|;\\s*)${name}=([^;]*)`))
-  return match?.[1]
-})
-```
-
-## Best Practices
-
-- Define keys/cached/cachedBy at **module level**, not inside handlers — they're descriptors, not values
-- Use `cached` for anything computed from request data — it guarantees single computation
-- Use `cachedBy` when computation varies by a parameter (cookie name, header name, etc.)
-- Async `cached` values cache the Promise — safe for concurrent access
-- Errors from `cached` are also cached — a failing computation won't retry
-
-## Gotchas
-
-- `key` throws on `get` if never `set` — use `ctx.has(k)` to check first
-- `cached` functions receive `ctx` as parameter — don't call `current()` inside them, use the provided `ctx`
-- Circular `cached` dependencies throw immediately — the cycle is detected at runtime
-- `cachedBy` uses a `Map` — keys are compared by identity (`===`), not deep equality