@kindgi/runtime 0.1.4 → 0.1.5

package/dist/bindings.d.ts

@@ -60,6 +60,8 @@ export interface RunBinding {
      */
     startRun(params: StartRunParams): Promise<Result<{
         readonly runId: RunId;
+        /** Set when `params.idempotencyKey` named a run that already exists: nothing new started. */
+        readonly existing?: true;
     }, StartRunError>>;
     /**
      * Delete a run + its journal + waitpoints. Retention path;

package/dist/bindings.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bindings.d.ts","sourceRoot":"","sources":["../src/bindings.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"bindings.d.ts","sourceRoot":"","sources":["../src/bindings.ts"],"names":[],"mappings":"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"}

package/dist/errors.d.ts

@@ -1,4 +1,4 @@
-export type KernelError = RunNotFoundError | FlowMismatchError | RunAlreadyTerminalError | NodeExecutionError | JournalError | WaitpointError | HandlerMissingError | StuckRunError | RunLeaseLostError;
+export type KernelError = RunNotFoundError | FlowMismatchError | RunAlreadyTerminalError | NodeExecutionError | JournalError | WaitpointError | HandlerMissingError | StuckRunError | RunLeaseLostError | RunExecutingError;
 export interface RunNotFoundError {
     readonly code: 'run-not-found';
     readonly message: string;
@@ -75,4 +75,14 @@ export interface RunLeaseLostError {
     readonly message: string;
     readonly runId: string;
 }
+/**
+ * The run is executing (an executor holds its lease), and the caller asked
+ * to end it only if it isn't: an erasure cancels a person's waiting turn,
+ * never one under a live executor, and tries again later.
+ */
+export interface RunExecutingError {
+    readonly code: 'run-executing';
+    readonly message: string;
+    readonly runId: string;
+}
 //# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,WAAW,GACnB,gBAAgB,GAChB,iBAAiB,GACjB,uBAAuB,GACvB,kBAAkB,GAClB,YAAY,GACZ,cAAc,GACd,mBAAmB,GACnB,aAAa,GACb,iBAAiB,CAAC;AAEtB,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAC/B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,oFAAoF;AACpF,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAC/B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE;QAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IACrE,QAAQ,CAAC,GAAG,EAAE;QAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CACjE;AAED,yFAAyF;AACzF,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,IAAI,EAAE,sBAAsB,CAAC;IACtC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,6EAA6E;AAC7E,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,IAAI,EAAE,sBAAsB,CAAC;IACtC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB;AAED,sDAAsD;AACtD,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAC/B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB;AAED,wEAAwE;AACxE,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;IACjC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;IACjC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAChC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,WAAW,GACnB,gBAAgB,GAChB,iBAAiB,GACjB,uBAAuB,GACvB,kBAAkB,GAClB,YAAY,GACZ,cAAc,GACd,mBAAmB,GACnB,aAAa,GACb,iBAAiB,GACjB,iBAAiB,CAAC;AAEtB,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAC/B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,oFAAoF;AACpF,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAC/B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE;QAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IACrE,QAAQ,CAAC,GAAG,EAAE;QAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CACjE;AAED,yFAAyF;AACzF,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,IAAI,EAAE,sBAAsB,CAAC;IACtC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,6EAA6E;AAC7E,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,IAAI,EAAE,sBAAsB,CAAC;IACtC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB;AAED,sDAAsD;AACtD,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAC/B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB;AAED,wEAAwE;AACxE,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;IACjC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;IACjC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAChC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAC/B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB"}

package/dist/inputs.d.ts

@@ -1,7 +1,7 @@
 import type { Principal } from '@kindgi/authz';
 import type { Flow, FlowVersionOverrides } from '@kindgi/flow';
 import type { HandlerRegistry } from '@kindgi/handler';
-import type { AgentVersionVia, ConversationId, LiveScope, NodeId, ProjectId, Result, RunId, ScopeSegment, TenantId } from '@kindgi/types';
+import type { AgentVersionVia, ConversationId, LiveScope, NodeId, ProjectId, Result, RunId, ScopeSegment, TenantId, Timestamp, TriggerId } from '@kindgi/types';
 import type { HandlerMissingError } from './errors.js';
 import type { KernelEventBusBinding } from './event-bus.js';
 import type { RunOptions } from './types.js';
@@ -57,6 +57,24 @@ export interface RunReplayRef {
     readonly of: RunId;
     readonly evalRunId: string;
 }
+/**
+ * Marks a run a trigger started: the trigger, the fire that started it,
+ * and for a schedule the occurrence it ran for.
+ */
+export interface RunTriggerRef {
+    readonly triggerId: TriggerId;
+    readonly kind: 'schedule' | 'event' | 'webhook';
+    readonly fireId: string;
+    /** A schedule's fire: the occurrence it ran for. */
+    readonly scheduledFor?: Timestamp;
+}
+/**
+ * The idempotency key of a run start: a start with a key a run of the
+ * tenant already has starts nothing and answers that run (`existing`), so
+ * a retried or re-driven start never runs twice. A trigger's fire uses
+ * `fire:<fireId>`. Keys are opaque, at most 255 characters.
+ */
+export type RunIdempotencyKey = 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
@@ -103,6 +121,14 @@ export interface RunFlowInput {
     readonly agent?: RunAgentRef;
     /** Set when an eval run is replaying a past run; see `RunReplayRef`. */
     readonly replay?: RunReplayRef;
+    /**
+     * Set when the run doesn't exist yet (no `runId`): start it at most once
+     * per key; see `RunIdempotencyKey`. A key a run already has runs nothing
+     * and answers that run's current state.
+     */
+    readonly idempotencyKey?: RunIdempotencyKey;
+    /** Set when a trigger started the run; see `RunTriggerRef`. */
+    readonly trigger?: RunTriggerRef;
     /**
      * The W3C trace id of the request that started the run (32 lowercase
      * hex), kept on the run so its later turns and resumes can name the
@@ -137,9 +163,15 @@ export interface RunFlowInput {
      */
     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.
+     * The Principal on whose authority this run executes: who started it
+     * (a caller, a schedule's creator, a service identity). Stored with
+     * the run, so every resume (an approval, a timeout, a child waking its
+     * flow, a run recovered after a crash) acts for the same principal.
+     * Only the start stores it: a pending run (`StartRunParams`) keeps the
+     * one it was started with, none included, whoever adopts it.
+     * When set together with `authz`, every `ctx.authorize` / `can` /
+     * `check` inside handlers is decided against it; on its own it only
+     * informs (e.g. whose own memory an agent turn may read).
      */
     readonly principal?: Principal;
     /**
@@ -168,11 +200,6 @@ export interface ResumeRunInput {
     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;
     };
@@ -190,12 +217,18 @@ export interface StartRunParams {
     readonly agent?: RunAgentRef;
     /** Set when an eval run is replaying a past run; see `RunReplayRef`. */
     readonly replay?: RunReplayRef;
+    /** Start it at most once per key; see `RunIdempotencyKey`. */
+    readonly idempotencyKey?: RunIdempotencyKey;
+    /** Set when a trigger started the run; see `RunTriggerRef`. */
+    readonly trigger?: RunTriggerRef;
     /** The trace id of the request that started the run; see `RunFlowInput.traceId`. */
     readonly traceId?: string;
     /** The versions the run swaps in over its flow version's pins; see `RunFlowInput.versions`. */
     readonly versions?: FlowVersionOverrides;
     /** The run's segment path; see `RunFlowInput.segments`. */
     readonly segments?: readonly ScopeSegment[];
+    /** Who starts the run; stored with it, see `RunFlowInput.principal`. */
+    readonly principal?: Principal;
 }
 export type StartRunError = {
     readonly code: 'insert-failed';

package/dist/inputs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"inputs.d.ts","sourceRoot":"","sources":["../src/inputs.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"inputs.d.ts","sourceRoot":"","sources":["../src/inputs.ts"],"names":[],"mappings":"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"}

package/dist/runs.d.ts

@@ -1,6 +1,6 @@
 import type { FlowVersionOverrides } from '@kindgi/flow';
-import type { Cursor, NodeId, OrgId, ProjectId, RunId, ScopeSegment, TenantId, Timestamp } from '@kindgi/types';
-import type { RunAgentRef } from './inputs.js';
+import type { Cursor, NodeId, OrgId, ProjectId, RunId, ScopeSegment, TenantId, Timestamp, TriggerId } from '@kindgi/types';
+import type { RunAgentRef, RunTriggerRef } from './inputs.js';
 import type { RunStatus } from './types.js';
 /**
  * Public run shape exposed by `RunBinding.getRun` / `.listRuns`.
@@ -45,6 +45,13 @@ export interface KernelRunRecord {
      * when it is a flow run. Absent when it was started without one.
      */
     readonly segments?: readonly ScopeSegment[];
+    /** Set on a run a trigger started (`RunTriggerRef`). */
+    readonly trigger?: RunTriggerRef;
+    /**
+     * When an erasure cleared the run's content (its input, output, failure
+     * message and journal payloads). Absent on every other run.
+     */
+    readonly contentErasedAt?: Timestamp;
     /**
      * The W3C trace id of the request that started the run
      * (`RunFlowInput.traceId`). Absent for a run no request started, and on
@@ -73,6 +80,12 @@ export type RunListScope = {
  * `{ createdAt, id }` internally.
  */
 export interface RunListCursor {
+    /**
+     * The last run's `createdAt`, as the binding's `nextCursor` carries it:
+     * as stored (Postgres keeps microseconds). A binding compares it as given,
+     * never through a JS `Date`, which keeps milliseconds and would skip the
+     * runs created earlier in the same millisecond.
+     */
     readonly createdAt: Timestamp;
     readonly id: RunId;
 }
@@ -98,6 +111,8 @@ export interface ListRunsInput {
     readonly replays?: 'exclude' | 'include' | 'only';
     /** Only the replays of this eval run. */
     readonly evalRunId?: string;
+    /** Only the runs this trigger started (`RunTriggerRef.triggerId`). */
+    readonly triggerId?: TriggerId;
 }
 export interface ListRunsPage {
     readonly data: readonly KernelRunRecord[];

package/dist/runs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runs.d.ts","sourceRoot":"","sources":["../src/runs.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"runs.d.ts","sourceRoot":"","sources":["../src/runs.ts"],"names":[],"mappings":"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"}

package/dist/schedulers/registry.d.ts

@@ -1,4 +1,4 @@
-import type { Cursor, Result, TenantId, TriggerId } from '@kindgi/types';
+import type { Cursor, LiveScope, ProjectId, Result, TenantId, TriggerId } from '@kindgi/types';
 import type { CronTriggerConfig, EventTriggerConfig, WebhookTriggerConfig } from './types.js';
 export interface TriggerRegistryBinding {
     register(input: RegisterTriggerInput): Promise<Result<TriggerRecord, RegisterTriggerError>>;
@@ -22,14 +22,123 @@ export interface TriggerRegistryBinding {
         readonly tenantId: TenantId;
         readonly webhookId: string;
     }): Promise<WebhookTriggerRecord | null>;
+    /**
+     * A trigger's fire history, newest first. Optional: without it, the
+     * route answers `501`.
+     */
+    listFires?(input: ListTriggerFiresInput): Promise<TriggerFirePage>;
+    /**
+     * Fire a schedule now, outside its schedule (`run-now`): one fire, recorded
+     * in its history with `manual: true`, starting one run as the schedule's
+     * owner. Optional: without it, the route answers `501`.
+     */
+    fireNow?(input: TriggerLifecycleInput): Promise<Result<TriggerFire, TriggerLifecycleError>>;
+    /**
+     * Make `owner` the principal a schedule's runs act as (an admin re-owns
+     * a schedule whose owner left). Optional: without it, the route answers
+     * `501`.
+     */
+    setOwner?(input: TriggerLifecycleInput & {
+        readonly owner: TriggerOwner;
+    }): Promise<Result<TriggerRecord, TriggerLifecycleError>>;
+}
+/**
+ * What a schedule runs: a flow at an exact version, or an agent. An agent
+ * that names no version runs its live version for the schedule's project,
+ * as a run that names none does. `improve` starts an improvement pass on
+ * an agent for a live scope when enough new trusted "no" judgments have
+ * come in (its input says how many, and the pass's options); otherwise
+ * its fire is `skipped`.
+ */
+export type TriggerTarget = {
+    readonly kind: 'flow';
+    readonly flowId: string;
+    readonly flowVersion: string;
+} | {
+    readonly kind: 'agent';
+    readonly agentId: string;
+    readonly agentVersion?: string;
+} | {
+    readonly kind: 'improve';
+    readonly agentId: string;
+    readonly scope: LiveScope;
+};
+/**
+ * The principal a trigger's runs act as: whoever registered it, until an
+ * admin re-owns it. Checked again at every fire.
+ */
+export interface TriggerOwner {
+    readonly kind: 'user' | 'service';
+    readonly id: string;
+}
+/**
+ * What a schedule does after a gap (the runtime was down, or the schedule
+ * was overdue past `startingDeadlineSeconds`): `latest` fires once, for
+ * the latest missed occurrence, recording how many it missed; `skip` drops
+ * the missed occurrences. Never every missed occurrence.
+ */
+export type ScheduleCatchUp = 'latest' | 'skip';
+/** When an occurrence comes while the schedule's previous run is still running. */
+export type ScheduleOverlap = 'skip' | 'allow';
+export declare const SCHEDULE_DEFAULTS: {
+    readonly catchUp: "latest";
+    readonly overlap: "skip";
+    readonly startingDeadlineSeconds: 600;
+};
+/**
+ * One fire of a trigger: an occurrence of a schedule (or a `run-now`), and
+ * what came of it. `pending` while its run is being started.
+ */
+export interface TriggerFire {
+    readonly fireId: string;
+    readonly triggerId: TriggerId;
+    readonly kind: 'schedule' | 'event' | 'webhook';
+    /** A schedule's fire: the occurrence it is for. */
+    readonly scheduledFor?: string;
+    readonly firedAt: string;
+    /**
+     * `skipped-erasure`: the person the fire acts for is being erased (the
+     * run start answered `erasure-in-progress`). Skipped fires never count
+     * toward the auto-pause; refused and failed ones do.
+     * `skipped`: what the target waits for wasn't there (an `improve`
+     * schedule's threshold, or its monthly cap), as `detail` says.
+     */
+    readonly outcome: 'pending' | 'started' | 'skipped-overlap' | 'skipped-erasure' | 'skipped' | 'refused' | 'failed';
+    /** The run it started, when it started one. */
+    readonly runId?: string;
+    /** The improvement pass it started, for an `improve` schedule. */
+    readonly passId?: string;
+    /** Why it was refused, skipped or failed. */
+    readonly detail?: string;
+    /** Occurrences this fire stood in for after a gap (`catchUp: 'latest'`). */
+    readonly missedCount?: number;
+    /** A `run-now` fire, outside the schedule. */
+    readonly manual?: boolean;
+}
+export interface ListTriggerFiresInput {
+    readonly tenantId: TenantId;
+    readonly triggerId: TriggerId;
+    readonly limit?: number;
+    readonly cursor?: Cursor;
+}
+export interface TriggerFirePage {
+    readonly data: readonly TriggerFire[];
+    readonly nextCursor?: Cursor;
 }
 export type RegisterTriggerInput = RegisterCronTriggerInput | RegisterEventTriggerInput | RegisterWebhookTriggerInput;
 export interface RegisterCronTriggerInput {
     readonly kind: 'cron';
     readonly tenantId: TenantId;
-    readonly flowId: string;
-    readonly flowVersion: string;
+    readonly target: TriggerTarget;
+    /** The schedule's project; absent → the tenant's default project. */
+    readonly projectId?: ProjectId;
+    /** Who its runs act as: the principal registering it. */
+    readonly owner: TriggerOwner;
     readonly config: CronTriggerConfig;
+    readonly catchUp?: ScheduleCatchUp;
+    readonly overlap?: ScheduleOverlap;
+    /** How late a fire may start and still count as on time; past it, `catchUp` applies. */
+    readonly startingDeadlineSeconds?: number;
     readonly label?: string;
 }
 export interface RegisterEventTriggerInput {
@@ -64,9 +173,14 @@ interface UpdateBase {
     /** Pin the trigger to a different flow version. */
     readonly flowVersion?: string;
 }
-export interface UpdateCronTriggerInput extends UpdateBase {
+export interface UpdateCronTriggerInput extends Omit<UpdateBase, 'flowVersion'> {
     readonly kind: 'cron';
     readonly config?: Partial<CronTriggerConfig>;
+    /** Run something else: another flow version, another agent version. */
+    readonly target?: TriggerTarget;
+    readonly catchUp?: ScheduleCatchUp;
+    readonly overlap?: ScheduleOverlap;
+    readonly startingDeadlineSeconds?: number;
 }
 export interface UpdateEventTriggerInput extends UpdateBase {
     readonly kind: 'event';
@@ -79,24 +193,37 @@ export interface UpdateWebhookTriggerInput extends UpdateBase {
 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;
 }
+/** An event trigger or an inbound webhook starts a flow at an exact version. */
+interface FlowTriggerRecordBase extends TriggerRecordBase {
+    readonly flowId: string;
+    readonly flowVersion: string;
+}
 export interface CronTriggerRecord extends TriggerRecordBase {
     readonly kind: 'cron';
+    readonly target: TriggerTarget;
+    readonly projectId: ProjectId;
+    readonly owner: TriggerOwner;
     readonly config: CronTriggerConfig;
+    readonly catchUp: ScheduleCatchUp;
+    readonly overlap: ScheduleOverlap;
+    readonly startingDeadlineSeconds: number;
     readonly nextFireAt: string | null;
+    /** Why the runtime paused it (repeated refused or failed fires; skipped ones never count), when it did. */
+    readonly statusReason?: string;
+    /** The next occurrences, when the read asked for them (`GetTriggerInput.upcoming`). */
+    readonly upcoming?: readonly string[];
 }
-export interface EventTriggerRecord extends TriggerRecordBase {
+export interface EventTriggerRecord extends FlowTriggerRecordBase {
     readonly kind: 'event';
     readonly config: EventTriggerConfig;
 }
-export interface WebhookTriggerRecord extends TriggerRecordBase {
+export interface WebhookTriggerRecord extends FlowTriggerRecordBase {
     readonly kind: 'webhook';
     readonly config: WebhookTriggerConfig;
     readonly webhookId: string;
@@ -117,6 +244,8 @@ export interface TriggerListPage {
 export interface GetTriggerInput {
     readonly tenantId: TenantId;
     readonly triggerId: TriggerId;
+    /** A schedule: include its next N occurrences (`CronTriggerRecord.upcoming`), at most 20. */
+    readonly upcoming?: number;
 }
 export interface TriggerLifecycleInput {
     readonly tenantId: TenantId;

package/dist/schedulers/registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/schedulers/registry.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/schedulers/registry.ts"],"names":[],"mappings":"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"}

package/dist/schedulers/registry.js

@@ -1,4 +1,9 @@
 // SPDX-License-Identifier: Apache-2.0
 // Copyright (C) 2026 Kindgi Inc.
+export const SCHEDULE_DEFAULTS = {
+    catchUp: 'latest',
+    overlap: 'skip',
+    startingDeadlineSeconds: 600,
+};
 export const TRIGGER_KINDS = ['cron', 'event', 'webhook'];
 //# sourceMappingURL=registry.js.map

package/dist/schedulers/registry.js.map

@@ -1 +1 @@
-{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/schedulers/registry.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC;AAkMjC,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,MAAM,EAAE,OAAO,EAAE,SAAS,CAAU,CAAC"}
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/schedulers/registry.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC;AAiGjC,MAAM,CAAC,MAAM,iBAAiB,GAAG;IAC/B,OAAO,EAAE,QAAQ;IACjB,OAAO,EAAE,MAAM;IACf,uBAAuB,EAAE,GAAG;CAK7B,CAAC;AA4OF,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,MAAM,EAAE,OAAO,EAAE,SAAS,CAAU,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kindgi/runtime",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "Kindgi™ runtime wire-vocabulary + binding interfaces. Public shape covering: RunStatus / RunResult / RunOptions / JournalEntry / JournalKind and all fanout/subgraph/iteration/step payload types; all kernel error shapes (KernelError, RunNotFoundError, HandlerMissingError, WaitpointError, etc.); run inputs and records (RunFlowInput / ResumeRunInput / StartRunParams, FlowResolver, HandlerResolver, ParentRunRef, KernelRunRecord, ListRunsInput); trigger schemas (Cron/Event/Webhook records + inputs + errors, plus TriggerRegistryBinding + RunFlowBinding + TRIGGER_KINDS); versioning envelope + wrap/unwrap; event-bus channel + KernelEventBusBinding; and the binding interfaces (RunBinding, SchedulerBinding, WaitpointBinding, RunRetentionBinding, umbrella KernelBinding) that deployments plug into `createApp`. Types + pure derivation functions — no runtime state, no dependency on a runtime implementation. The Kindgi runtime implements the bindings.",
   "license": "Apache-2.0",
   "repository": {
@@ -28,10 +28,10 @@
     "README.md"
   ],
   "dependencies": {
-    "@kindgi/authz": "0.1.4",
-    "@kindgi/flow": "0.1.4",
-    "@kindgi/handler": "0.1.4",
-    "@kindgi/types": "0.1.4"
+    "@kindgi/authz": "0.1.5",
+    "@kindgi/flow": "0.1.5",
+    "@kindgi/handler": "0.1.5",
+    "@kindgi/types": "0.1.5"
   },
   "engines": {
     "node": ">=22.12.0"

package/src/bindings.ts

@@ -106,7 +106,16 @@ export interface RunBinding {
    * `wait: false` answering `202`, subgraph child dispatch); the run
    * is then executed with `runGraph({ ..., runId })`.
    */
-  startRun(params: StartRunParams): Promise<Result<{ readonly runId: RunId }, StartRunError>>;
+  startRun(params: StartRunParams): Promise<
+    Result<
+      {
+        readonly runId: RunId;
+        /** Set when `params.idempotencyKey` named a run that already exists: nothing new started. */
+        readonly existing?: true;
+      },
+      StartRunError
+    >
+  >;
 
   /**
    * Delete a run + its journal + waitpoints. Retention path;

package/src/errors.ts

@@ -10,7 +10,8 @@ export type KernelError =
   | WaitpointError
   | HandlerMissingError
   | StuckRunError
-  | RunLeaseLostError;
+  | RunLeaseLostError
+  | RunExecutingError;
 
 export interface RunNotFoundError {
   readonly code: 'run-not-found';
@@ -90,3 +91,14 @@ export interface RunLeaseLostError {
   readonly message: string;
   readonly runId: string;
 }
+
+/**
+ * The run is executing (an executor holds its lease), and the caller asked
+ * to end it only if it isn't: an erasure cancels a person's waiting turn,
+ * never one under a live executor, and tries again later.
+ */
+export interface RunExecutingError {
+  readonly code: 'run-executing';
+  readonly message: string;
+  readonly runId: string;
+}

package/src/inputs.ts

@@ -14,6 +14,8 @@ import type {
   RunId,
   ScopeSegment,
   TenantId,
+  Timestamp,
+  TriggerId,
 } from '@kindgi/types';
 
 import type { HandlerMissingError } from './errors.js';
@@ -76,6 +78,26 @@ export interface RunReplayRef {
   readonly evalRunId: string;
 }
 
+/**
+ * Marks a run a trigger started: the trigger, the fire that started it,
+ * and for a schedule the occurrence it ran for.
+ */
+export interface RunTriggerRef {
+  readonly triggerId: TriggerId;
+  readonly kind: 'schedule' | 'event' | 'webhook';
+  readonly fireId: string;
+  /** A schedule's fire: the occurrence it ran for. */
+  readonly scheduledFor?: Timestamp;
+}
+
+/**
+ * The idempotency key of a run start: a start with a key a run of the
+ * tenant already has starts nothing and answers that run (`existing`), so
+ * a retried or re-driven start never runs twice. A trigger's fire uses
+ * `fire:<fireId>`. Keys are opaque, at most 255 characters.
+ */
+export type RunIdempotencyKey = 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
@@ -123,6 +145,14 @@ export interface RunFlowInput {
   readonly agent?: RunAgentRef;
   /** Set when an eval run is replaying a past run; see `RunReplayRef`. */
   readonly replay?: RunReplayRef;
+  /**
+   * Set when the run doesn't exist yet (no `runId`): start it at most once
+   * per key; see `RunIdempotencyKey`. A key a run already has runs nothing
+   * and answers that run's current state.
+   */
+  readonly idempotencyKey?: RunIdempotencyKey;
+  /** Set when a trigger started the run; see `RunTriggerRef`. */
+  readonly trigger?: RunTriggerRef;
   /**
    * The W3C trace id of the request that started the run (32 lowercase
    * hex), kept on the run so its later turns and resumes can name the
@@ -157,9 +187,15 @@ export interface RunFlowInput {
    */
   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.
+   * The Principal on whose authority this run executes: who started it
+   * (a caller, a schedule's creator, a service identity). Stored with
+   * the run, so every resume (an approval, a timeout, a child waking its
+   * flow, a run recovered after a crash) acts for the same principal.
+   * Only the start stores it: a pending run (`StartRunParams`) keeps the
+   * one it was started with, none included, whoever adopts it.
+   * When set together with `authz`, every `ctx.authorize` / `can` /
+   * `check` inside handlers is decided against it; on its own it only
+   * informs (e.g. whose own memory an agent turn may read).
    */
   readonly principal?: Principal;
   /**
@@ -189,11 +225,8 @@ export interface ResumeRunInput {
   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;
+  // No principal: a resumed run acts for the one stored when it started
+  // (`RunFlowInput.principal`); a resume can't drop or change it.
   readonly authz?: {
     readonly fgaApiUrl: string;
   };
@@ -212,12 +245,18 @@ export interface StartRunParams {
   readonly agent?: RunAgentRef;
   /** Set when an eval run is replaying a past run; see `RunReplayRef`. */
   readonly replay?: RunReplayRef;
+  /** Start it at most once per key; see `RunIdempotencyKey`. */
+  readonly idempotencyKey?: RunIdempotencyKey;
+  /** Set when a trigger started the run; see `RunTriggerRef`. */
+  readonly trigger?: RunTriggerRef;
   /** The trace id of the request that started the run; see `RunFlowInput.traceId`. */
   readonly traceId?: string;
   /** The versions the run swaps in over its flow version's pins; see `RunFlowInput.versions`. */
   readonly versions?: FlowVersionOverrides;
   /** The run's segment path; see `RunFlowInput.segments`. */
   readonly segments?: readonly ScopeSegment[];
+  /** Who starts the run; stored with it, see `RunFlowInput.principal`. */
+  readonly principal?: Principal;
 }
 
 export type StartRunError = { readonly code: 'insert-failed'; readonly message: string };

package/src/runs.ts

@@ -18,9 +18,10 @@ import type {
   ScopeSegment,
   TenantId,
   Timestamp,
+  TriggerId,
 } from '@kindgi/types';
 
-import type { RunAgentRef } from './inputs.js';
+import type { RunAgentRef, RunTriggerRef } from './inputs.js';
 import type { RunStatus } from './types.js';
 
 /**
@@ -66,6 +67,13 @@ export interface KernelRunRecord {
    * when it is a flow run. Absent when it was started without one.
    */
   readonly segments?: readonly ScopeSegment[];
+  /** Set on a run a trigger started (`RunTriggerRef`). */
+  readonly trigger?: RunTriggerRef;
+  /**
+   * When an erasure cleared the run's content (its input, output, failure
+   * message and journal payloads). Absent on every other run.
+   */
+  readonly contentErasedAt?: Timestamp;
   /**
    * The W3C trace id of the request that started the run
    * (`RunFlowInput.traceId`). Absent for a run no request started, and on
@@ -92,6 +100,12 @@ export type RunListScope =
  * `{ createdAt, id }` internally.
  */
 export interface RunListCursor {
+  /**
+   * The last run's `createdAt`, as the binding's `nextCursor` carries it:
+   * as stored (Postgres keeps microseconds). A binding compares it as given,
+   * never through a JS `Date`, which keeps milliseconds and would skip the
+   * runs created earlier in the same millisecond.
+   */
   readonly createdAt: Timestamp;
   readonly id: RunId;
 }
@@ -118,6 +132,8 @@ export interface ListRunsInput {
   readonly replays?: 'exclude' | 'include' | 'only';
   /** Only the replays of this eval run. */
   readonly evalRunId?: string;
+  /** Only the runs this trigger started (`RunTriggerRef.triggerId`). */
+  readonly triggerId?: TriggerId;
 }
 
 export interface ListRunsPage {

package/src/schedulers/registry.ts

@@ -5,7 +5,7 @@
 // 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 { Cursor, LiveScope, ProjectId, Result, TenantId, TriggerId } from '@kindgi/types';
 
 import type { CronTriggerConfig, EventTriggerConfig, WebhookTriggerConfig } from './types.js';
 
@@ -37,6 +37,125 @@ export interface TriggerRegistryBinding {
     readonly tenantId: TenantId;
     readonly webhookId: string;
   }): Promise<WebhookTriggerRecord | null>;
+
+  /**
+   * A trigger's fire history, newest first. Optional: without it, the
+   * route answers `501`.
+   */
+  listFires?(input: ListTriggerFiresInput): Promise<TriggerFirePage>;
+
+  /**
+   * Fire a schedule now, outside its schedule (`run-now`): one fire, recorded
+   * in its history with `manual: true`, starting one run as the schedule's
+   * owner. Optional: without it, the route answers `501`.
+   */
+  fireNow?(input: TriggerLifecycleInput): Promise<Result<TriggerFire, TriggerLifecycleError>>;
+
+  /**
+   * Make `owner` the principal a schedule's runs act as (an admin re-owns
+   * a schedule whose owner left). Optional: without it, the route answers
+   * `501`.
+   */
+  setOwner?(
+    input: TriggerLifecycleInput & { readonly owner: TriggerOwner },
+  ): Promise<Result<TriggerRecord, TriggerLifecycleError>>;
+}
+
+// ---------- schedules: what they run, who as, and when ----------
+
+/**
+ * What a schedule runs: a flow at an exact version, or an agent. An agent
+ * that names no version runs its live version for the schedule's project,
+ * as a run that names none does. `improve` starts an improvement pass on
+ * an agent for a live scope when enough new trusted "no" judgments have
+ * come in (its input says how many, and the pass's options); otherwise
+ * its fire is `skipped`.
+ */
+export type TriggerTarget =
+  | { readonly kind: 'flow'; readonly flowId: string; readonly flowVersion: string }
+  | { readonly kind: 'agent'; readonly agentId: string; readonly agentVersion?: string }
+  | { readonly kind: 'improve'; readonly agentId: string; readonly scope: LiveScope };
+
+/**
+ * The principal a trigger's runs act as: whoever registered it, until an
+ * admin re-owns it. Checked again at every fire.
+ */
+export interface TriggerOwner {
+  readonly kind: 'user' | 'service';
+  readonly id: string;
+}
+
+/**
+ * What a schedule does after a gap (the runtime was down, or the schedule
+ * was overdue past `startingDeadlineSeconds`): `latest` fires once, for
+ * the latest missed occurrence, recording how many it missed; `skip` drops
+ * the missed occurrences. Never every missed occurrence.
+ */
+export type ScheduleCatchUp = 'latest' | 'skip';
+
+/** When an occurrence comes while the schedule's previous run is still running. */
+export type ScheduleOverlap = 'skip' | 'allow';
+
+export const SCHEDULE_DEFAULTS = {
+  catchUp: 'latest',
+  overlap: 'skip',
+  startingDeadlineSeconds: 600,
+} as const satisfies {
+  readonly catchUp: ScheduleCatchUp;
+  readonly overlap: ScheduleOverlap;
+  readonly startingDeadlineSeconds: number;
+};
+
+// ---------- fires ----------
+
+/**
+ * One fire of a trigger: an occurrence of a schedule (or a `run-now`), and
+ * what came of it. `pending` while its run is being started.
+ */
+export interface TriggerFire {
+  readonly fireId: string;
+  readonly triggerId: TriggerId;
+  readonly kind: 'schedule' | 'event' | 'webhook';
+  /** A schedule's fire: the occurrence it is for. */
+  readonly scheduledFor?: string;
+  readonly firedAt: string;
+  /**
+   * `skipped-erasure`: the person the fire acts for is being erased (the
+   * run start answered `erasure-in-progress`). Skipped fires never count
+   * toward the auto-pause; refused and failed ones do.
+   * `skipped`: what the target waits for wasn't there (an `improve`
+   * schedule's threshold, or its monthly cap), as `detail` says.
+   */
+  readonly outcome:
+    | 'pending'
+    | 'started'
+    | 'skipped-overlap'
+    | 'skipped-erasure'
+    | 'skipped'
+    | 'refused'
+    | 'failed';
+  /** The run it started, when it started one. */
+  readonly runId?: string;
+  /** The improvement pass it started, for an `improve` schedule. */
+  readonly passId?: string;
+  /** Why it was refused, skipped or failed. */
+  readonly detail?: string;
+  /** Occurrences this fire stood in for after a gap (`catchUp: 'latest'`). */
+  readonly missedCount?: number;
+  /** A `run-now` fire, outside the schedule. */
+  readonly manual?: boolean;
+}
+
+export interface ListTriggerFiresInput {
+  readonly tenantId: TenantId;
+  readonly triggerId: TriggerId;
+  readonly limit?: number;
+  readonly cursor?: Cursor;
+}
+
+export interface TriggerFirePage {
+  readonly data: readonly TriggerFire[];
+  readonly nextCursor?: Cursor;
 }
 
 // ---------- register (discriminated on kind) ----------
@@ -49,9 +168,16 @@ export type RegisterTriggerInput =
 export interface RegisterCronTriggerInput {
   readonly kind: 'cron';
   readonly tenantId: TenantId;
-  readonly flowId: string;
-  readonly flowVersion: string;
+  readonly target: TriggerTarget;
+  /** The schedule's project; absent → the tenant's default project. */
+  readonly projectId?: ProjectId;
+  /** Who its runs act as: the principal registering it. */
+  readonly owner: TriggerOwner;
   readonly config: CronTriggerConfig;
+  readonly catchUp?: ScheduleCatchUp;
+  readonly overlap?: ScheduleOverlap;
+  /** How late a fire may start and still count as on time; past it, `catchUp` applies. */
+  readonly startingDeadlineSeconds?: number;
   readonly label?: string;
 }
 
@@ -96,9 +222,14 @@ interface UpdateBase {
   readonly flowVersion?: string;
 }
 
-export interface UpdateCronTriggerInput extends UpdateBase {
+export interface UpdateCronTriggerInput extends Omit<UpdateBase, 'flowVersion'> {
   readonly kind: 'cron';
   readonly config?: Partial<CronTriggerConfig>;
+  /** Run something else: another flow version, another agent version. */
+  readonly target?: TriggerTarget;
+  readonly catchUp?: ScheduleCatchUp;
+  readonly overlap?: ScheduleOverlap;
+  readonly startingDeadlineSeconds?: number;
 }
 
 export interface UpdateEventTriggerInput extends UpdateBase {
@@ -117,8 +248,6 @@ export interface UpdateWebhookTriggerInput extends UpdateBase {
 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;
@@ -126,18 +255,34 @@ interface TriggerRecordBase {
   readonly updatedAt: string;
 }
 
+/** An event trigger or an inbound webhook starts a flow at an exact version. */
+interface FlowTriggerRecordBase extends TriggerRecordBase {
+  readonly flowId: string;
+  readonly flowVersion: string;
+}
+
 export interface CronTriggerRecord extends TriggerRecordBase {
   readonly kind: 'cron';
+  readonly target: TriggerTarget;
+  readonly projectId: ProjectId;
+  readonly owner: TriggerOwner;
   readonly config: CronTriggerConfig;
+  readonly catchUp: ScheduleCatchUp;
+  readonly overlap: ScheduleOverlap;
+  readonly startingDeadlineSeconds: number;
   readonly nextFireAt: string | null;
+  /** Why the runtime paused it (repeated refused or failed fires; skipped ones never count), when it did. */
+  readonly statusReason?: string;
+  /** The next occurrences, when the read asked for them (`GetTriggerInput.upcoming`). */
+  readonly upcoming?: readonly string[];
 }
 
-export interface EventTriggerRecord extends TriggerRecordBase {
+export interface EventTriggerRecord extends FlowTriggerRecordBase {
   readonly kind: 'event';
   readonly config: EventTriggerConfig;
 }
 
-export interface WebhookTriggerRecord extends TriggerRecordBase {
+export interface WebhookTriggerRecord extends FlowTriggerRecordBase {
   readonly kind: 'webhook';
   readonly config: WebhookTriggerConfig;
   readonly webhookId: string;
@@ -164,6 +309,8 @@ export interface TriggerListPage {
 export interface GetTriggerInput {
   readonly tenantId: TenantId;
   readonly triggerId: TriggerId;
+  /** A schedule: include its next N occurrences (`CronTriggerRecord.upcoming`), at most 20. */
+  readonly upcoming?: number;
 }
 
 export interface TriggerLifecycleInput {