@kindgi/handler 0.1.1 → 0.1.3

package/README.md

@@ -14,7 +14,7 @@ code.
 | Symbol | Kind | What it is |
 | --- | --- | --- |
 | `NodeHandler` | type | `(input: unknown, ctx: NodeContext) => Promise<HandlerResult \| unknown>` |
-| `NodeContext` | type | What handlers receive: `runId`, `nodeId`, `tenantId`, `nodeOutputs`, `state`, `abortSignal`, `dryRun`, `principal?`, `authorize`, `can`, `check`, `clockNow`, `waitForToken` |
+| `NodeContext` | type | What handlers receive: `runId`, `nodeId`, `tenantId`, `nodeOutputs`, `state`, `abortSignal`, `dryRun`, `principal?`, `authorize`, `can`, `check`, `clockNow`, `record`, `waitForToken` |
 | `HandlerResult` | type | Optional structured return — `{ output, stateDelta? }` |
 | `HandlerRegistry` | type | `ReadonlyMap<NodeId, NodeHandler>` |
 | `LoopContext` | type | Loop annotation (`loopNodeId`, `iteration`, enclosing-loop `path`) on the journal entries of nodes that ran inside a loop body |

package/dist/types.d.ts

@@ -1,5 +1,5 @@
 import type { Action, Decision, Principal, ResourceRef } from '@kindgi/authz';
-import type { NodeId, RunId, TenantId } from '@kindgi/types';
+import type { NodeId, OrgId, ProjectId, RunId, TenantId } from '@kindgi/types';
 /**
  * A node handler is the concrete code the runtime invokes when a flow
  * node becomes ready. The handler is entirely user-authored; the
@@ -50,6 +50,13 @@ export interface NodeContext {
     readonly nodeId: NodeId;
     /** The tenant this run belongs to — required for any tenant-scoped I/O. */
     readonly tenantId: TenantId;
+    /**
+     * The project this run belongs to, from the run (never from its input).
+     * Optional on the type: a test harness may build a context without one.
+     */
+    readonly projectId?: ProjectId;
+    /** That project's org, when it has one; resolved by the runtime from the project. */
+    readonly orgId?: OrgId;
     /**
      * Read-only outputs of previously-completed nodes, keyed by `NodeId`.
      * Present for fan-in and cross-branch reads.
@@ -102,8 +109,33 @@ export interface NodeContext {
     can(action: Action, resource: ResourceRef): Promise<boolean>;
     /** Full Decision — for advanced cases needing reason/evidence. */
     check(action: Action, resource: ResourceRef): Promise<Decision>;
-    /** Read the clock. First call journals `Date.now()`; on replay, returns the journaled value. */
+    /**
+     * Read the clock, as `record` does: each call journals `Date.now()`.
+     * When the step resumes after a wait, its first call returns the time
+     * the first call read before, its second the second's, and so on; calls
+     * past those read the clock. A retry after a failure reads it afresh.
+     * **Determinism:** call it in the same order every time the step runs.
+     */
     clockNow(): Promise<number>;
+    /**
+     * Decide once for this step. The first call for `key` runs `decide`,
+     * journals its result, then returns it. When the step runs again
+     * (resumed after a wait, or retried after a failure), the call returns
+     * the journaled result and `decide` doesn't run, whatever the data it
+     * decided from says now.
+     *
+     * For a decision the step must keep across a wait: an approval gate's
+     * (did the policy ask for a review, under which token), so a policy
+     * changed meanwhile can't undo the park or lose the reviewer's answer.
+     *
+     * - The result is kept as JSON, and returned as JSON the first time too
+     *   (a `Date` comes back as its string): `decide` returns JSON data.
+     * - `undefined` isn't journaled: the next call decides again.
+     * - `key` names the decision within the step; a step in a loop body
+     *   keeps one per iteration. Calls for one key at the same time share
+     *   one decision.
+     */
+    record<T>(key: string, decide: () => T | Promise<T>): Promise<T>;
     /**
      * Suspend the handler and wait for an external `completeToken(tokenId,
      * value)`. On first invocation: journals `wait.suspended`, inserts a

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC9E,OAAO,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE7D;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,WAAW,KAAK,OAAO,CAAC,aAAa,GAAG,OAAO,CAAC,CAAC;AAEjG;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB;;;OAGG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACzD;AAED;;;;GAIG;AACH,MAAM,MAAM,eAAe,GAAG,WAAW,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;AAE/D;;;;;;;;GAQG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,2EAA2E;IAC3E,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B;;;OAGG;IACH,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnD,yEAAyE;IACzE,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAClD;;;;;;;;;OASG;IACH,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;IAClC;;;;;;;OAOG;IACH,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB;;;;;;;;OAQG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,CAAC;IAC/B;;;;;;;;;OASG;IACH,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAChE,qEAAqE;IACrE,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC7D,kEAAkE;IAClE,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,WAAW,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IAChE,gGAAgG;IAChG,QAAQ,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IAC5B;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,YAAY,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CAChF;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,SAAS;QAAE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CACvF;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,cAAc,CAAC,MAAM,GAAG,OAAO;IAC9C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,gBAAgB,GAAG,gBAAgB,GAAG,iBAAiB,CAAC;IAC7E,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACtC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@kindgi/handler",
-  "version": "0.1.1",
-  "description": "Kindgi™ pack-author authoring surface. The types a pack author writes handlers against: NodeHandler (the function signature), NodeContext (what handlers receive at invocation — run scope, sibling outputs, waitForToken, authorize, clockNow, etc.), HandlerResult (structured return with optional stateDelta), HandlerRegistry (NodeId → NodeHandler map), LoopContext + LoopNodeOutput (loop-node shapes), plus WaitpointCancelledError (thrown by waitForToken when the wait is cancelled externally). Types plus that one error class — no other runtime code. Every runtime that executes Kindgi handlers implements this contract.",
+  "version": "0.1.3",
+  "description": "Kindgi™ pack-author authoring surface. The types a pack author writes handlers against: NodeHandler (the function signature), NodeContext (what handlers receive at invocation — run scope, sibling outputs, waitForToken, authorize, clockNow, record, etc.), HandlerResult (structured return with optional stateDelta), HandlerRegistry (NodeId → NodeHandler map), LoopContext + LoopNodeOutput (loop-node shapes), plus WaitpointCancelledError (thrown by waitForToken when the wait is cancelled externally). Types plus that one error class — no other runtime code. Every runtime that executes Kindgi handlers implements this contract.",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -18,7 +18,8 @@
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
     }
   },
   "files": [
@@ -27,11 +28,11 @@
     "README.md"
   ],
   "dependencies": {
-    "@kindgi/authz": "0.1.1",
-    "@kindgi/types": "0.1.1"
+    "@kindgi/authz": "0.1.3",
+    "@kindgi/types": "0.1.3"
   },
   "engines": {
-    "node": ">=22.0.0"
+    "node": ">=22.12.0"
   },
   "publishConfig": {
     "access": "public",

package/src/types.ts

@@ -2,7 +2,7 @@
 // Copyright (C) 2026 Kindgi Inc.
 
 import type { Action, Decision, Principal, ResourceRef } from '@kindgi/authz';
-import type { NodeId, RunId, TenantId } from '@kindgi/types';
+import type { NodeId, OrgId, ProjectId, RunId, TenantId } from '@kindgi/types';
 
 /**
  * A node handler is the concrete code the runtime invokes when a flow
@@ -57,6 +57,13 @@ export interface NodeContext {
   readonly nodeId: NodeId;
   /** The tenant this run belongs to — required for any tenant-scoped I/O. */
   readonly tenantId: TenantId;
+  /**
+   * The project this run belongs to, from the run (never from its input).
+   * Optional on the type: a test harness may build a context without one.
+   */
+  readonly projectId?: ProjectId;
+  /** That project's org, when it has one; resolved by the runtime from the project. */
+  readonly orgId?: OrgId;
   /**
    * Read-only outputs of previously-completed nodes, keyed by `NodeId`.
    * Present for fan-in and cross-branch reads.
@@ -109,8 +116,33 @@ export interface NodeContext {
   can(action: Action, resource: ResourceRef): Promise<boolean>;
   /** Full Decision — for advanced cases needing reason/evidence. */
   check(action: Action, resource: ResourceRef): Promise<Decision>;
-  /** Read the clock. First call journals `Date.now()`; on replay, returns the journaled value. */
+  /**
+   * Read the clock, as `record` does: each call journals `Date.now()`.
+   * When the step resumes after a wait, its first call returns the time
+   * the first call read before, its second the second's, and so on; calls
+   * past those read the clock. A retry after a failure reads it afresh.
+   * **Determinism:** call it in the same order every time the step runs.
+   */
   clockNow(): Promise<number>;
+  /**
+   * Decide once for this step. The first call for `key` runs `decide`,
+   * journals its result, then returns it. When the step runs again
+   * (resumed after a wait, or retried after a failure), the call returns
+   * the journaled result and `decide` doesn't run, whatever the data it
+   * decided from says now.
+   *
+   * For a decision the step must keep across a wait: an approval gate's
+   * (did the policy ask for a review, under which token), so a policy
+   * changed meanwhile can't undo the park or lose the reviewer's answer.
+   *
+   * - The result is kept as JSON, and returned as JSON the first time too
+   *   (a `Date` comes back as its string): `decide` returns JSON data.
+   * - `undefined` isn't journaled: the next call decides again.
+   * - `key` names the decision within the step; a step in a loop body
+   *   keeps one per iteration. Calls for one key at the same time share
+   *   one decision.
+   */
+  record<T>(key: string, decide: () => T | Promise<T>): Promise<T>;
   /**
    * Suspend the handler and wait for an external `completeToken(tokenId,
    * value)`. On first invocation: journals `wait.suspended`, inserts a