@kindgi/runtime 0.0.0-bootstrap.0 → 0.1.1

package/src/event-bus.ts

@@ -0,0 +1,51 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import type { Result, TenantId } from '@kindgi/types';
+
+/**
+ * Minimal structural interface the kernel calls into after each
+ * successful journal write. Deliberately narrower than
+ * `@kindgi/api`'s `EventBusBinding` so the kernel can accept
+ * either the API-side binding OR a plain publish-only shim without
+ * a hard dependency on `@kindgi/api`.
+ *
+ * The full binding (with `subscribe`) is defined in
+ * `packages/api/src/event-bus-binding.ts`. That type is structurally
+ * assignable to this one — a caller wiring the same instance into
+ * both sides just works.
+ *
+ * `publish` MUST NOT throw. Errors are returned in the `Result` so
+ * the kernel can log-and-continue: a publish failure MUST NOT roll
+ * back the journal append (that would be a correctness bug — the
+ * journal is the source of truth).
+ */
+export interface KernelEventBusBinding {
+  publish(
+    tenantId: TenantId,
+    channel: string,
+    doc: unknown,
+  ): Promise<Result<void, { readonly message: string }>>;
+  /**
+   * Publish `docs` to the channel, in order, as one write. The kernel
+   * writes a run's journal entries in batches and publishes each batch
+   * with this when the binding has it, and entry by entry with
+   * `publish` otherwise. Same contract as `publish`: never throws.
+   */
+  publishMany?(
+    tenantId: TenantId,
+    channel: string,
+    docs: readonly unknown[],
+  ): Promise<Result<void, { readonly message: string }>>;
+}
+
+/**
+ * Derived per-run channel name. Every kernel journal write publishes
+ * to this channel; SSE consumers subscribe with the same shape.
+ *
+ * Deliberately colon-namespaced so other channels (e.g.
+ * `kernel:trigger:<id>`) cannot collide with it.
+ */
+export function kernelRunChannel(runId: string): string {
+  return `kernel:run:${runId}`;
+}

package/src/index.ts

@@ -0,0 +1,13 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+export * from './types.js';
+export * from './errors.js';
+export * from './derivation.js';
+export * from './versioning.js';
+export * from './event-bus.js';
+export * from './schedulers/types.js';
+export * from './schedulers/registry.js';
+export * from './inputs.js';
+export * from './runs.js';
+export * from './bindings.js';

package/src/inputs.ts

@@ -0,0 +1,169 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import type { Principal } from '@kindgi/authz';
+import type { Flow } from '@kindgi/flow';
+import type { HandlerRegistry } from '@kindgi/handler';
+import type { NodeId, ProjectId, Result, RunId, TenantId } from '@kindgi/types';
+
+import type { HandlerMissingError } from './errors.js';
+import type { KernelEventBusBinding } from './event-bus.js';
+import type { RunOptions } from './types.js';
+
+/**
+ * Resolver contract for `subgraph` node dispatch. Structurally
+ * satisfied by `FlowRegistryBinding.getVersion(...)` in `@kindgi/api`.
+ * The runtime invokes the resolver with the PARENT run's tenantId; a
+ * flow registered under a different tenant returns `null`, which is
+ * the cross-tenant guarantee (rejection at dispatch with
+ * `subgraph-flow-not-found` attribution).
+ */
+export interface FlowResolver {
+  getVersion(input: {
+    readonly tenantId: TenantId;
+    readonly flowId: string;
+    readonly version: string;
+  }): Promise<Flow | null>;
+}
+
+/**
+ * The node in a parent run that started this run as its child — a
+ * subgraph node's sub-run, or the agent turn an agent step launches.
+ * Stored on the child's row, so a parent (or a caller) can find the
+ * children of a run, and a resumed child can wake the parent that waits
+ * on it.
+ */
+export interface ParentRunRef {
+  readonly runId: RunId;
+  readonly nodeId: NodeId;
+  /**
+   * Distinguishes children of the same node — one per loop iteration.
+   * The enclosing loop stack, serialized; `''` for a node outside any
+   * loop.
+   */
+  readonly scope: string;
+}
+
+/**
+ * Binds the handlers for a flow the runtime is about to run or resume —
+ * the root flow and every child flow a subgraph node starts. Lets a
+ * child flow get handlers for its own nodes instead of sharing the
+ * parent's registry.
+ */
+export interface HandlerResolver {
+  resolve(input: {
+    readonly tenantId: TenantId;
+    readonly projectId: ProjectId;
+    readonly flow: Flow;
+    readonly dryRun: boolean;
+  }): Promise<Result<HandlerRegistry, HandlerMissingError>>;
+}
+
+export interface RunFlowInput {
+  readonly tenantId: TenantId;
+  /**
+   * Content-scope anchor. REQUIRED — every kernel run is bound to
+   * exactly one project inside the tenant. Callers without a natural
+   * project id resolve to the tenant's Default via
+   * `projectBinding.getDefault(tenantId)` at the caller layer.
+   */
+  readonly projectId: ProjectId;
+  readonly flow: Flow;
+  readonly handlers: HandlerRegistry;
+  readonly input: unknown;
+  readonly options?: RunOptions;
+  /**
+   * Optional flow resolver — required for flows that contain
+   * `subgraph` nodes. Absent resolver → subgraph nodes fail
+   * immediately with reason `resolver-missing`.
+   */
+  readonly flowResolver?: FlowResolver;
+  /**
+   * Internal: subgraph depth of THIS run. Populated by the runtime
+   * when a parent's `subgraph` node dispatches a child. External
+   * callers do NOT set this — it always starts at `0` for a
+   * top-level `RunBinding.runGraph` call.
+   */
+  readonly subgraphDepth?: number;
+  /** The parent node that started this run, when it is a child run. */
+  readonly parent?: ParentRunRef;
+  /**
+   * Run an existing `pending` row (created by `startRun`) instead of
+   * inserting a new one — how a caller hands back a run id before the
+   * run finishes.
+   */
+  readonly runId?: RunId;
+  /** Handlers for child flows; see `HandlerResolver`. */
+  readonly handlerResolver?: HandlerResolver;
+  /**
+   * Optional push-based event bus. When set, the runtime publishes
+   * a `JournalEntry`-shaped `doc` to `kernel:run:<runId>` after each
+   * successful journal write. When absent, journal writes still land
+   * durably.
+   */
+  readonly eventBus?: KernelEventBusBinding;
+  /**
+   * Authorization — the Principal on whose authority this run
+   * executes. When set together with `authz`, every `ctx.authorize` /
+   * `can` / `check` inside handlers is decided against this principal.
+   */
+  readonly principal?: Principal;
+  /**
+   * Authorization config — enables authorization checks inside the
+   * runtime. When absent, `ctx.authorize` is a no-op and tool
+   * invocations skip their pre-flight check.
+   */
+  readonly authz?: {
+    readonly fgaApiUrl: string;
+  };
+}
+
+export interface ResumeRunInput {
+  readonly tenantId: TenantId;
+  readonly runId: RunId;
+  readonly flow: Flow;
+  readonly handlers: HandlerRegistry;
+  readonly options?: RunOptions;
+  /** Same shape as `RunFlowInput.flowResolver`. */
+  readonly flowResolver?: FlowResolver;
+  /**
+   * Internal: subgraph depth of THIS run when it was originally
+   * started. Callers on the top level do NOT set this.
+   */
+  readonly subgraphDepth?: number;
+  /** Same shape + semantics as `RunFlowInput.handlerResolver`. */
+  readonly handlerResolver?: HandlerResolver;
+  /** Same shape + semantics as `RunFlowInput.eventBus`. */
+  readonly eventBus?: KernelEventBusBinding;
+  /**
+   * Authorization — carried through on resume so the resumed run
+   * keeps enforcing per-tool + per-subgraph checks.
+   */
+  readonly principal?: Principal;
+  readonly authz?: {
+    readonly fgaApiUrl: string;
+  };
+}
+
+export interface StartRunParams {
+  readonly tenantId: TenantId;
+  readonly projectId: ProjectId;
+  readonly flowId: string;
+  readonly flowVersion: string;
+  readonly input: unknown;
+  readonly dryRun?: boolean;
+  /** The parent node that starts this run, when it is a child run. */
+  readonly parent?: ParentRunRef;
+}
+
+export type StartRunError = { readonly code: 'insert-failed'; readonly message: string };
+
+export interface DeleteRunParams {
+  readonly tenantId: TenantId;
+  readonly runId: RunId;
+}
+
+export type DeleteRunError = {
+  readonly code: 'not-found' | 'delete-failed';
+  readonly message?: string;
+};

package/src/runs.ts

@@ -0,0 +1,84 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+//
+// KernelRunRecord + list/get shapes — the public projection of a run
+// that RunBinding exposes. Deliberately narrower than what an
+// implementation stores: bookkeeping such as retention or cache markers
+// is not part of this shape.
+//
+
+import type { Cursor, NodeId, OrgId, ProjectId, RunId, TenantId, Timestamp } from '@kindgi/types';
+
+import type { RunStatus } from './types.js';
+
+/**
+ * Public run shape exposed by `RunBinding.getRun` / `.listRuns`.
+ * Matches the fields @kindgi/api's `/v1/runs` routes serialize to
+ * the wire.
+ */
+export interface KernelRunRecord {
+  readonly runId: RunId;
+  readonly tenantId: TenantId;
+  readonly projectId: ProjectId;
+  readonly flowId: string;
+  readonly flowVersion: string;
+  readonly status: RunStatus;
+  readonly input: unknown;
+  /** The run's output once it completed — the value itself, not a storage envelope. */
+  readonly output?: unknown;
+  readonly failureMessage?: string | null;
+  readonly dryRun: boolean;
+  readonly createdAt: Timestamp;
+  readonly updatedAt: Timestamp;
+  readonly completedAt?: Timestamp | null;
+  /** Set on a child run: the parent run and the node that started it (`ParentRunRef`). */
+  readonly parentRunId?: RunId | null;
+  readonly parentNodeId?: NodeId | null;
+  readonly parentScope?: string | null;
+}
+
+/**
+ * Content-scope filter for `RunBinding.listRuns`. Present-with-value
+ * narrows to a specific project or org; absent = tenant-wide (admin
+ * default). An org scope includes the runs of every project in that
+ * org.
+ */
+export type RunListScope =
+  | { readonly kind: 'project'; readonly projectId: ProjectId }
+  | { readonly kind: 'org'; readonly orgId: OrgId };
+
+/**
+ * Cursor position for `RunBinding.listRuns`. Sort key is
+ * `(createdAt desc, id desc)` — same discipline as every other
+ * kernel-facing list. Callers pass the opaque `Cursor` string
+ * decoded from the wire; the impl decodes it back to
+ * `{ createdAt, id }` internally.
+ */
+export interface RunListCursor {
+  readonly createdAt: Timestamp;
+  readonly id: RunId;
+}
+
+export interface ListRunsInput {
+  readonly tenantId: TenantId;
+  readonly scope?: RunListScope;
+  readonly limit?: number;
+  readonly cursor?: RunListCursor;
+  /**
+   * Only the children of this run — optionally only those a given node
+   * (and loop scope) started.
+   */
+  readonly parent?: {
+    readonly runId: RunId;
+    readonly nodeId?: NodeId;
+    readonly scope?: string;
+  };
+  /** Only runs that are not a child of another run. */
+  readonly topLevelOnly?: boolean;
+}
+
+export interface ListRunsPage {
+  readonly data: readonly KernelRunRecord[];
+  readonly nextCursor?: Cursor;
+}

package/src/schedulers/registry.ts

@@ -0,0 +1,197 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+// Public trigger-registry shape: binding interface, register/update/list
+// input variants, record shapes, error shapes, TRIGGER_KINDS constant.
+// The implementation is supplied by the Kindgi runtime.
+
+import type { Cursor, Result, TenantId, TriggerId } from '@kindgi/types';
+
+import type { CronTriggerConfig, EventTriggerConfig, WebhookTriggerConfig } from './types.js';
+
+export interface TriggerRegistryBinding {
+  register(input: RegisterTriggerInput): Promise<Result<TriggerRecord, RegisterTriggerError>>;
+
+  update(input: UpdateTriggerInput): Promise<Result<TriggerRecord, UpdateTriggerError>>;
+
+  list(input: ListTriggersInput): Promise<TriggerListPage>;
+
+  get(input: GetTriggerInput): Promise<TriggerRecord | null>;
+
+  pause(input: TriggerLifecycleInput): Promise<Result<TriggerRecord, TriggerLifecycleError>>;
+
+  resume(input: TriggerLifecycleInput): Promise<Result<TriggerRecord, TriggerLifecycleError>>;
+
+  unregister(
+    input: TriggerLifecycleInput,
+  ): Promise<{ readonly triggerId: TriggerId; readonly unregistered: boolean }>;
+
+  /**
+   * Webhook-receiver hot path. The receiver resolves the HMAC secret
+   * named by `hmacSecretName` from the tenant's secrets (`SecretBinding`
+   * in `@kindgi/api`) and verifies the request before spawning. Returns
+   * null when webhookId is unknown, the trigger is tombstoned, or
+   * `status !== 'active'`.
+   */
+  fetchActiveByWebhookId(input: {
+    readonly tenantId: TenantId;
+    readonly webhookId: string;
+  }): Promise<WebhookTriggerRecord | null>;
+}
+
+// ---------- register (discriminated on kind) ----------
+
+export type RegisterTriggerInput =
+  | RegisterCronTriggerInput
+  | RegisterEventTriggerInput
+  | RegisterWebhookTriggerInput;
+
+export interface RegisterCronTriggerInput {
+  readonly kind: 'cron';
+  readonly tenantId: TenantId;
+  readonly flowId: string;
+  readonly flowVersion: string;
+  readonly config: CronTriggerConfig;
+  readonly label?: string;
+}
+
+export interface RegisterEventTriggerInput {
+  readonly kind: 'event';
+  readonly tenantId: TenantId;
+  readonly flowId: string;
+  readonly flowVersion: string;
+  readonly config: EventTriggerConfig;
+  readonly label?: string;
+}
+
+export interface RegisterWebhookTriggerInput {
+  readonly kind: 'webhook';
+  readonly tenantId: TenantId;
+  readonly flowId: string;
+  readonly flowVersion: string;
+  readonly config: WebhookTriggerConfig;
+  /** Caller-supplied (uuid). The routable id a webhook receiver looks the trigger up by. */
+  readonly webhookId: string;
+  /**
+   * Name of the HMAC secret in the tenant's secrets store. The caller
+   * writes the secret first (`POST /v1/secrets`); this row never holds it.
+   */
+  readonly hmacSecretName: string;
+  readonly label?: string;
+}
+
+// ---------- update (discriminated on kind) ----------
+
+export type UpdateTriggerInput =
+  | UpdateCronTriggerInput
+  | UpdateEventTriggerInput
+  | UpdateWebhookTriggerInput;
+
+interface UpdateBase {
+  readonly tenantId: TenantId;
+  readonly triggerId: TriggerId;
+  /** `null` clears the label; omitted leaves it unchanged. */
+  readonly label?: string | null;
+  /** Pin the trigger to a different flow version. */
+  readonly flowVersion?: string;
+}
+
+export interface UpdateCronTriggerInput extends UpdateBase {
+  readonly kind: 'cron';
+  readonly config?: Partial<CronTriggerConfig>;
+}
+
+export interface UpdateEventTriggerInput extends UpdateBase {
+  readonly kind: 'event';
+  readonly config?: Partial<EventTriggerConfig>;
+}
+
+export interface UpdateWebhookTriggerInput extends UpdateBase {
+  readonly kind: 'webhook';
+  readonly config?: Partial<WebhookTriggerConfig>;
+  // HMAC secret rotation flows through /v1/secrets — not here.
+}
+
+// ---------- records (discriminated on kind) ----------
+
+interface TriggerRecordBase {
+  readonly triggerId: TriggerId;
+  readonly tenantId: TenantId;
+  readonly flowId: string;
+  readonly flowVersion: string;
+  readonly status: 'active' | 'paused';
+  readonly label: string | null;
+  readonly lastFiredAt: string | null;
+  readonly createdAt: string;
+  readonly updatedAt: string;
+}
+
+export interface CronTriggerRecord extends TriggerRecordBase {
+  readonly kind: 'cron';
+  readonly config: CronTriggerConfig;
+  readonly nextFireAt: string | null;
+}
+
+export interface EventTriggerRecord extends TriggerRecordBase {
+  readonly kind: 'event';
+  readonly config: EventTriggerConfig;
+}
+
+export interface WebhookTriggerRecord extends TriggerRecordBase {
+  readonly kind: 'webhook';
+  readonly config: WebhookTriggerConfig;
+  readonly webhookId: string;
+  readonly hmacSecretName: string;
+}
+
+export type TriggerRecord = CronTriggerRecord | EventTriggerRecord | WebhookTriggerRecord;
+
+// ---------- list + get + lifecycle ----------
+
+export interface ListTriggersInput {
+  readonly tenantId: TenantId;
+  readonly kind?: TriggerKind;
+  readonly status?: 'active' | 'paused';
+  readonly limit?: number;
+  readonly cursor?: Cursor;
+}
+
+export interface TriggerListPage {
+  readonly data: readonly TriggerRecord[];
+  readonly nextCursor?: Cursor;
+}
+
+export interface GetTriggerInput {
+  readonly tenantId: TenantId;
+  readonly triggerId: TriggerId;
+}
+
+export interface TriggerLifecycleInput {
+  readonly tenantId: TenantId;
+  readonly triggerId: TriggerId;
+}
+
+// ---------- errors ----------
+
+export interface RegisterTriggerError {
+  readonly code:
+    | 'trigger-invalid-config'
+    | 'trigger-webhook-id-conflict'
+    | 'trigger-register-failed';
+  readonly message: string;
+}
+
+export interface UpdateTriggerError {
+  readonly code: 'trigger-not-found' | 'trigger-invalid-config' | 'trigger-update-failed';
+  readonly message: string;
+  readonly triggerId: TriggerId;
+}
+
+export interface TriggerLifecycleError {
+  readonly code: 'trigger-not-found' | 'trigger-already-in-state' | 'trigger-lifecycle-failed';
+  readonly message: string;
+  readonly triggerId: TriggerId;
+}
+
+export const TRIGGER_KINDS = ['cron', 'event', 'webhook'] as const;
+export type TriggerKind = (typeof TRIGGER_KINDS)[number];

package/src/schedulers/types.ts

@@ -0,0 +1,112 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import type { EventId, Result, RunId, TenantId, TriggerId } from '@kindgi/types';
+
+/**
+ * What the trigger runtime hands to a caller-supplied `RunFlowBinding`.
+ *
+ * The kernel doesn't own a flow registry — resolving `flowId + flowVersion`
+ * to a concrete `Flow + HandlerRegistry` is deployment-specific (packs
+ * register at boot, dev consumers pass in inline maps, etc.). The binding
+ * shape lets any of those wire in without the kernel choosing for them.
+ */
+export interface TriggerFireContext {
+  readonly tenantId: TenantId;
+  readonly flowId: string;
+  readonly flowVersion: string;
+  /**
+   * Input to hand to `runGraph`. Shape is trigger-kind-specific:
+   *   - cron:    `config.input ?? {}` (the caller pre-shapes at register time).
+   *   - event:   the entire `Event` object — handler decides which fields
+   *              it cares about.
+   *   - webhook: parsed request body — the receiver route decides whether
+   *              to JSON.parse or hand raw bytes to the binding.
+   */
+  readonly input: unknown;
+  readonly source: TriggerSource;
+}
+
+/** Discriminated origin of the run spawn, useful for provenance / audit. */
+export type TriggerSource =
+  | { readonly kind: 'cron'; readonly triggerId: TriggerId }
+  | {
+      readonly kind: 'event';
+      readonly triggerId: TriggerId;
+      readonly eventId: EventId;
+      readonly eventKind: string;
+    }
+  | { readonly kind: 'webhook'; readonly triggerId: TriggerId; readonly webhookId: string };
+
+/**
+ * The caller-supplied hook that turns a trigger fire into a real run. The
+ * kernel calls this for every due tick, every matching event, every valid
+ * webhook receive. Deployments wire it to their own flow+handler lookup
+ * (packs manifest, in-process registry, etc.) and then call `runGraph`.
+ */
+export type RunFlowBinding = (
+  ctx: TriggerFireContext,
+) => Promise<Result<{ readonly runId: RunId }, TriggerBindingError>>;
+
+/** Errors the caller-supplied binding is allowed to surface. */
+export interface TriggerBindingError {
+  readonly code: 'flow-not-found' | 'handler-missing' | 'run-spawn-failed';
+  readonly message: string;
+  readonly cause?: unknown;
+}
+
+/**
+ * Union of every error the trigger runtime primitives can return. The
+ * kind-specific shapes are declared below.
+ */
+export type TriggerError = WebhookTriggerError | CronTriggerError | EventTriggerError;
+
+export interface WebhookTriggerError {
+  readonly code:
+    | 'webhook-not-found'
+    | 'webhook-signature-invalid'
+    | 'webhook-inactive'
+    | 'webhook-flow-not-found';
+  readonly message: string;
+  readonly webhookId: string;
+}
+
+export interface CronTriggerError {
+  readonly code: 'cron-config-invalid' | 'cron-flow-not-found';
+  readonly message: string;
+  readonly triggerId: TriggerId;
+}
+
+export interface EventTriggerError {
+  readonly code: 'event-config-invalid' | 'event-flow-not-found';
+  readonly message: string;
+  readonly triggerId: TriggerId;
+}
+
+/** Trigger-kind-specific config shapes, stored as each trigger's `config`. */
+export interface CronTriggerConfig {
+  /** 5- or 6-field cron expression (croner-compatible). 6-field enables second precision. */
+  readonly cronExpression: string;
+  /** IANA timezone (e.g. 'UTC', 'America/New_York'). Defaults to 'UTC'. */
+  readonly timezone?: string;
+  /** Static input handed to the flow on every fire. Absent → `{}`. */
+  readonly input?: unknown;
+}
+
+export interface EventTriggerConfig {
+  /** Event type filter (matched against `event.type`). */
+  readonly eventKind: string;
+  /**
+   * Optional input override. When absent, the entire `Event` object is
+   * passed as the flow input.
+   */
+  readonly input?: unknown;
+}
+
+export interface WebhookTriggerConfig {
+  /**
+   * Optional input override. When absent, the parsed request body (as
+   * passed to `fireByWebhookId`) is used as the flow input.
+   */
+  readonly input?: unknown;
+}