okengine 0.19.9 → 0.20.0

package/site/content/docs/elements/flow/http.mdx

@@ -299,12 +299,15 @@ export const get = on(
 );
 ```
 
+Declared `out` projects the row — return it as-is (Date or `fx.clock.now()` epoch-ms → ISO-8601; extra columns strip).
+
 </Tab>
 
 <Tab value="POST">
 
-Create a resource or run a command. `fx.json.create(value)` returns `201 Created` with
-`{ data: value, error: null }`:
+Create a resource or run a command. `fx.json.create(row)` returns `201 Created` with
+`{ data: value, error: null }`. Declared `out` projects the store row (Date / epoch-ms → ISO).
+HTTP `in` timestamps are ISO (`z.iso.datetime()`); store writes coerce them to `Date`.
 
 ```typescript title="src/flows/notes/create.ts"
 import { on, flow, http } from "okengine";
@@ -319,8 +322,8 @@ export const create = on(
   flow({
     do: async ({ title }, fx) => {
       const id = fx.id();
-      await fx.store(db).insert(notes).values({ id, title });
-      return fx.json.create({ id, title });
+      const [row] = await fx.store(db).insert(notes).values({ id, title }).returning();
+      return fx.json.create(row);
     },
   }),
 );
@@ -934,8 +937,9 @@ Every HTTP flow returns the same envelope shape. You choose status and optional
 custom wrapper.
 
 <Callout title="Envelope is fixed">
-  Success and failure always use `{ data, error }` (optional top-level `meta`). There is no API to
-  replace that shape. Use `fx.json.*` for status codes and `meta`; use `fx.fail` for typed errors.
+  Success and failure always use `{ data, error }` (optional top-level `meta`). Use `fx.json.*` for
+  status and `meta`; use `fx.fail` for typed errors. A raw `Response` from `do` is the exception —
+  `302` + `Location` for redirects.
 </Callout>
 
 **Success** — returning a value from `do` produces `200 OK`:
@@ -946,14 +950,21 @@ custom wrapper.
 
 Returning `undefined` produces a `204 No Content` response with an empty body.
 
-**Custom status** — `fx.json.create` for `201 Created`, or `fx.json.ok` with optional `meta`:
+**Custom status** — `fx.json.create` for `201 Created`, or `fx.json.ok` with optional `meta`.
+When `out` is set, pass the store row — the kernel projects it (Date → ISO-8601; extra keys strip):
 
 ```typescript
-return fx.json.create({ id: "ord_1" });
+return fx.json.create(row);
 // or
 return fx.json.ok({ id: "ord_1" }, { meta: { traceId: fx.runId } });
 ```
 
+**Redirects** — return a raw `Response` so the kernel does not wrap `{ data, error }`:
+
+```typescript
+return new Response(null, { status: 302, headers: { Location: url } });
+```
+
 **Typed failures** — `fx.fail(code, data)` formats the error envelope and maps status:
 
 ```typescript
@@ -1004,6 +1015,11 @@ Standard status code mappings:
   `error.data.issues` array for the specific field validation failure.
 </Accordion>
 
+<Accordion title="I mapped Date columns to ISO by hand">
+  Declared `out` already projects store rows. `fx.json.create(row)`, `return row`, and
+  `fx.json.withQuery(rows, input)` are enough — extra columns strip. A miss is not a client error.
+</Accordion>
+
 <Accordion title="Browser blocked by CORS / missing Access-Control-*">
   Cross-origin access is closed until you plug the [`cors`](/docs/plugins/cors) plugin with an
   explicit `origin`. Same-origin calls need no CORS headers. Preflight `OPTIONS` is answered by the

package/site/content/docs/elements/flow/index.mdx

@@ -96,19 +96,19 @@ export const ping = on(
 
 `in` / `out` live on the HTTP bag. Invalid input never enters `do`:
 
-```typescript title="src/flows/notes/create.ts"
+```typescript title="src/flows/links/create.ts"
 import { on, flow, http } from "okengine";
 import { z } from "zod";
 
 export const create = on(
   http.post({
-    in: z.object({ title: z.string().min(1) }),
-    out: z.object({ id: z.string(), title: z.string() }),
+    in: z.object({ url: z.string().url() }),
+    out: z.object({ id: z.string(), url: z.string() }),
   }),
   flow({
-    do: async ({ title }, fx) => {
+    do: async ({ url }, fx) => {
       const id = fx.id();
-      return { id, title };
+      return { id, url };
     },
   }),
 );
@@ -238,11 +238,14 @@ Invoke contracts (`in` / `out` / `errors` / `breaking`) belong on the exposure
 ## Contracts
 
 <Callout title="Detailed section">
-  Invoke contracts live on the **exposure** — `http.post({ in, out, errors })`, `call("name", {
-  in, out, do })`, or `mcp.tool("x", { in, out })`. The Manifest still shows flat
-  `flows.*.{in,out,errors,breaking}` as a projection from that exposure. `in` runs before `do`;
-  `out` runs after a successful return. `fx.fail` skips `out`. Signal / Channel `schema` is a
-  separate **emit** contract (validated at `fx.emit` / `fx.send`).
+  Invoke contracts live on the **exposure** (`http.post({ in, out, errors })`, `call("name", { in,
+  out, do })`, `mcp.tool("x", { in, out })`). Manifest `flows.*` is a projection from that bag.
+
+`in` validates before `do`. After success, `out` projects the reply (Date → ISO-8601, extra keys
+strip); a miss is not a client error. `fx.fail` skips `out`.
+
+Signal / Channel `schema` is a separate **emit** contract (validated at `fx.emit` / `fx.send`).
+
 </Callout>
 
 <Tabs items={["Standard Schema", "Failures", "Envelope"]}>
@@ -344,8 +347,8 @@ A bare `404` with body `Not Found` means **no route matched** — not `fx.fail("
 </Accordion>
 
 <Accordion title="Name stamping">
-  Prefer nameless `flow({ do })` on HTTP tree files — `src/flows/notes/[id]/get.ts` +
-  `export const get` stamps `notes.get`. Signal / Clock workers pass `flow("name", { do })`
+  Prefer nameless `flow({ do })` on HTTP tree files — `src/flows/links/[code]/get.ts` +
+  `export const get` stamps `links.get`. Signal / Clock workers pass `flow("name", { do })`
   (**OKE1072**; Clock inline is [Clock · Inline or named export](/docs/elements/clock#inline-or-named-export)).
 </Accordion>