@kindgi/runtime 0.0.0-bootstrap.0 → 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,317 @@
+import type { LoopContext } from '@kindgi/handler';
+import type { NodeId, ProjectId, RunId, TenantId, Timestamp } from '@kindgi/types';
+/** Terminal states are `completed`, `failed`, `cancelled`. */
+export type RunStatus = 'pending' | 'running' | 'suspended' | 'completed' | 'failed' | 'cancelled';
+export interface RunResult<TOutput = unknown> {
+    readonly runId: RunId;
+    readonly status: RunStatus;
+    /**
+     * For completed runs: the flow's declared output (`Flow.output`) when the
+     * flow has one; otherwise the output of the node whose edge reached
+     * `$end`. When multiple `$end`-terminating edges fire, one is picked
+     * deterministically (lowest edge id in traversal order).
+     */
+    readonly output?: TOutput;
+    readonly failureMessage?: string;
+    /** Free-form projectId echoed back if the run was bound to one. */
+    readonly projectId?: ProjectId;
+    readonly tenantId: TenantId;
+}
+/** Kernel journal entry kinds. */
+export type JournalKind = 'run.started' | 'step.started' | 'step.completed' | 'step.failed' | 'step.retry-scheduled' | 'step.concurrency-deferred' | 'edge.evaluated' | 'iteration.started' | 'iteration.completed' | 'fanout.dispatched' | 'fanout.branch-completed' | 'fanout.branch-failed' | 'fanout.converged' | 'fanout.cancelled-siblings' | 'subgraph.dispatched' | 'subgraph.completed' | 'subgraph.failed' | 'subgraph.cancelled' | 'run.completed' | 'run.failed' | 'run.cancelled' | 'wait.suspended' | 'wait.resumed' | 'wait.cancelled' | 'clock.read';
+/**
+ * Journal payload for `step.retry-scheduled`. Emitted when a node handler
+ * fails but the destination's sole incoming edge carries a `retry` policy
+ * with attempts remaining. The executor waits `nextDelayMs` (subject to the
+ * backoff shape) then re-dispatches the node.
+ *
+ * `attempt` is 1-based: `1` means the first retry (following the initial
+ * failure), `2` the second, etc. The number of `step.retry-scheduled`
+ * entries for a given node is the attempt count at derivation time.
+ */
+export interface StepRetryScheduledPayload {
+    readonly nodeId: NodeId;
+    readonly attempt: number;
+    readonly nextDelayMs: number;
+    readonly previousError: string;
+}
+/**
+ * Journal payload for `step.concurrency-deferred`. Emitted when the
+ * dispatcher attempts to acquire a `policy.concurrencyKey` lease for a
+ * ready node and the lease is already held. The node stays in the ready
+ * set (from the scheduler's POV) but is deferred for the current tick;
+ * on the next tick, after the current holder releases, one waiter
+ * acquires and dispatches.
+ *
+ * `holderRunId` + `holderNodeId` attribute the current holder so an
+ * operator can debug "why is my node stuck?" without looking up other runs.
+ * `holderRunId` may equal the deferred node's run (self-contention) or a
+ * different run in the same tenant.
+ *
+ * Multiple `step.concurrency-deferred` entries for the same node are
+ * expected under long-held leases — derivation records only that the
+ * node is in the deferred bucket, not the count.
+ */
+export interface StepConcurrencyDeferredPayload {
+    readonly nodeId: NodeId;
+    readonly concurrencyKey: string;
+    readonly holderRunId: RunId;
+    readonly holderNodeId: NodeId;
+}
+/**
+ * Journal payload doc shape for `iteration.started`.
+ *
+ * `bodyExecuted` is `false` only when a `while` loop with
+ * `evaluationTiming: 'before'` short-circuits its exit check before the
+ * body runs — in that case `exitConditionResult` is populated on
+ * `iteration.started` (and `iteration.completed` isn't emitted for the
+ * skipped iteration).
+ */
+export interface IterationStartedPayload {
+    readonly iteration: number;
+    readonly bodyExecuted: boolean;
+    readonly exitConditionResult?: boolean | undefined;
+    readonly loopContext?: LoopContext | undefined;
+}
+/**
+ * Journal payload doc shape for `iteration.completed`.
+ *
+ * `outputSchemaValid` records whether the iteration's `$loop-end` output
+ * validated against the loop's `outputSchema`. On failure, `stopReason`
+ * is `'output-schema-violation'` and `schemaErrors` is populated.
+ *
+ * For `while` loops with `evaluationTiming: 'after'`, `exitConditionResult`
+ * is populated. For `while+before`, the check happens on the NEXT
+ * iteration's `iteration.started` and is absent here. For `foreach`, no
+ * exit condition — absent.
+ *
+ * `stopReason` is only populated on the FINAL iteration (the one that
+ * caused the loop to exit). Intermediate iterations have it as undefined.
+ */
+export interface IterationCompletedPayload {
+    readonly iteration: number;
+    readonly output: unknown;
+    readonly outputSchemaValid: boolean;
+    readonly schemaErrors?: readonly unknown[] | undefined;
+    readonly exitConditionResult?: boolean | undefined;
+    readonly stopReason?: 'exit-condition' | 'max-iterations' | 'array-exhausted' | 'output-schema-violation' | 'body-failure' | 'cancelled' | 'iterate-over-not-array' | undefined;
+    readonly loopContext?: LoopContext | undefined;
+}
+/**
+ * Journal payload for `fanout.dispatched`. Emitted once per branch, before
+ * the branch handler is invoked. `input` is the same value every branch of
+ * the fanout receives (the fanout node's own resolved input).
+ */
+export interface FanoutDispatchedPayload {
+    readonly fanoutNodeId: NodeId;
+    readonly branchId: string;
+    readonly handler: string;
+    readonly input: unknown;
+}
+/**
+ * Journal payload for `fanout.branch-completed`. Emitted when a branch's
+ * handler returns AND the resulting output validates against the branch's
+ * declared `outputSchema`.
+ */
+export interface FanoutBranchCompletedPayload {
+    readonly fanoutNodeId: NodeId;
+    readonly branchId: string;
+    readonly output: unknown;
+}
+/**
+ * Journal payload for `fanout.branch-failed`. Emitted when a branch fails.
+ * `reason` narrows the failure attribution so consumers do not have to
+ * match on the message. `schemaErrors` is populated when
+ * `reason === 'output-schema-violation'`.
+ */
+export interface FanoutBranchFailedPayload {
+    readonly fanoutNodeId: NodeId;
+    readonly branchId: string;
+    readonly message: string;
+    readonly reason: 'handler-throw' | 'output-schema-violation' | 'cancelled';
+    readonly schemaErrors?: readonly unknown[];
+}
+/**
+ * Journal payload for `fanout.converged`. Emitted once, after the fanout
+ * finalizes on a successful convergence. Carries the fan-in-shaped output
+ * that will be handed to downstream consumers via `nodeOutputs`.
+ */
+export interface FanoutConvergedPayload {
+    readonly fanoutNodeId: NodeId;
+    readonly convergence: 'all-succeed' | 'any-succeed' | 'settle-all';
+    readonly output: unknown;
+}
+/**
+ * Journal payload for `fanout.cancelled-siblings`. Emitted once, when the
+ * convergence mode short-circuits (all-succeed on first failure OR
+ * any-succeed on first success) and in-flight sibling branches are
+ * cancelled. `reason` records which convergence trigger fired;
+ * `cancelledBranchIds` enumerates every branch that received the abort
+ * signal (whether or not it had already settled — the journal captures
+ * intent).
+ */
+export interface FanoutCancelledSiblingsPayload {
+    readonly fanoutNodeId: NodeId;
+    readonly cancelledBranchIds: readonly string[];
+    readonly reason: 'first-failure' | 'first-success';
+}
+/**
+ * Fan-in shape emitted by a fanout node whose convergence mode is
+ * `'all-succeed'`. Object keyed by every branchId, mapping to that
+ * branch's validated output.
+ */
+export interface FanoutAllSucceedOutput {
+    readonly [branchId: string]: unknown;
+}
+/**
+ * Fan-in shape emitted by a fanout node whose convergence mode is
+ * `'any-succeed'`. Records the identity of the winning branch and its
+ * validated output. In-flight siblings were cancelled and do not appear.
+ */
+export interface FanoutAnySucceedOutput {
+    readonly winnerBranchId: string;
+    readonly output: unknown;
+}
+/**
+ * Per-branch outcome inside a `'settle-all'` fan-in output. `status` is
+ * `'succeeded'` when the branch handler returned a schema-valid output
+ * (present in `output`), `'failed'` when the branch failed (handler
+ * threw OR output schema violation, message in `error`).
+ */
+export interface FanoutSettleAllBranchOutcome {
+    readonly status: 'succeeded' | 'failed';
+    readonly output?: unknown;
+    readonly error?: string;
+}
+/**
+ * Fan-in shape emitted by a fanout node whose convergence mode is
+ * `'settle-all'`. Object keyed by every branchId, mapping to that
+ * branch's terminal outcome.
+ */
+export interface FanoutSettleAllOutput {
+    readonly [branchId: string]: FanoutSettleAllBranchOutcome;
+}
+/**
+ * Journal payload for `subgraph.dispatched`. Emitted before the child
+ * kernel run is started, so restarts observe consistent parent-journal
+ * state. Carries the child `runId` so replay can resolve back to the
+ * exact sub-run (rather than re-dispatching a fresh one).
+ */
+export interface SubflowDispatchedPayload {
+    readonly subgraphNodeId: NodeId;
+    readonly subRunId: RunId;
+    readonly flowRef: {
+        readonly flowId: string;
+        readonly version: string;
+    };
+    readonly subInput: unknown;
+    readonly depth: number;
+}
+/**
+ * Journal payload for `subgraph.completed`. Emitted when the child kernel
+ * run reaches `status: 'completed'` AND its terminal output validates
+ * against the parent's declared `outputSchema`. `validatedOutput` is the
+ * schema-valid value; the parent node's own `step.completed` follows,
+ * with an output shape decided by the parent's `convergence` mode.
+ */
+export interface SubflowCompletedPayload {
+    readonly subgraphNodeId: NodeId;
+    readonly subRunId: RunId;
+    readonly output: unknown;
+}
+/**
+ * Journal payload for `subgraph.failed`. Emitted when the child run
+ * failed OR its terminal output failed schema validation. Attribution:
+ *   - `child-failed`   → child kernel run terminated with `failed` status.
+ *   - `output-schema-violation` → child completed but its output did not
+ *     match the parent's declared `outputSchema`.
+ *   - `subgraph-flow-not-found` → resolver returned null at dispatch.
+ *   - `subgraph-depth-exceeded` → parent's `RunOptions.maxSubflowDepth`
+ *     was hit at dispatch.
+ *   - `subgraph-cross-tenant` → attempted lookup of a flow registered
+ *     under a different tenant (reserved — cannot happen with the current
+ *     resolver contract but journaled defensively).
+ *   - `resolver-missing` → the run was started without a `flowResolver`
+ *     dependency wired in, so the subgraph node cannot dispatch.
+ */
+export interface SubflowFailedPayload {
+    readonly subgraphNodeId: NodeId;
+    readonly subRunId?: RunId;
+    readonly flowRef?: {
+        readonly flowId: string;
+        readonly version: string;
+    };
+    readonly reason: 'child-failed' | 'output-schema-violation' | 'subgraph-flow-not-found' | 'subgraph-depth-exceeded' | 'subgraph-cross-tenant' | 'resolver-missing';
+    readonly message: string;
+    readonly schemaErrors?: readonly unknown[];
+}
+/**
+ * Journal payload for `subgraph.cancelled`. Emitted when the parent run is
+ * being torn down (external `cancelRun`) OR when a sibling handler failed
+ * and the composed abort signal cascades to the child. Under `settle-all`
+ * convergence, the parent step still transitions to `step.completed` with
+ * an `error` envelope; under `success-only`, the parent step transitions
+ * to `step.failed`.
+ */
+export interface SubflowCancelledPayload {
+    readonly subgraphNodeId: NodeId;
+    readonly subRunId: RunId;
+    readonly stopReason: 'cancelled';
+}
+/**
+ * Fan-in shape emitted by a `subgraph` node whose convergence mode is
+ * `'success-only'`. When the child run succeeded and its output
+ * validated, the parent node's output IS the validated child output.
+ * No wrapping envelope. When the child fails, the parent step
+ * transitions to `step.failed` (no output written).
+ */
+export type SubflowSuccessOnlyOutput = unknown;
+/**
+ * Fan-in shape emitted by a `subgraph` node whose convergence mode is
+ * `'settle-all'`. Always a settled envelope: on success the `output`
+ * carries the schema-valid child output; on failure the `error` names
+ * the attribution.
+ */
+export interface SubflowSettleAllOutput {
+    readonly status: 'succeeded' | 'failed';
+    readonly output?: unknown;
+    readonly error?: string;
+}
+export interface JournalEntry {
+    readonly sequence: number;
+    readonly kind: JournalKind;
+    readonly nodeId?: NodeId;
+    readonly payload?: unknown;
+    readonly timestamp: Timestamp;
+}
+/** Kernel run-configuration knobs. */
+export interface RunOptions {
+    /**
+     * Maximum number of node handlers dispatched concurrently in a single
+     * tick. Prevents accidental self-DoS on downstream systems from wide
+     * fan-outs. Default: 8.
+     */
+    readonly maxParallelism?: number;
+    /**
+     * When `true`, the run executes in dry-run mode: `NodeContext.dryRun`
+     * is exposed to every handler so they can self-mock side-effecting
+     * calls (tool invocation, model calls, DB writes). The run record is
+     * marked `dryRun: true` (`KernelRunRecord.dryRun`); the journal shape is
+     * unchanged. Consumers (the client's `runs.dryRun`, cost estimators,
+     * plan viewers) filter on that flag. Default: `false`.
+     */
+    readonly dryRun?: boolean;
+    /**
+     * Maximum sub-flow invocation depth. A parent run at depth 0 that
+     * dispatches a `subgraph` node produces a child at depth 1; the child
+     * dispatching its own subgraph node produces a grandchild at depth 2;
+     * and so on. Exceeding this cap fails the subgraph node at dispatch
+     * with `subgraph-depth-exceeded`. Default: 10. Configured on the
+     * outermost `RunBinding.runGraph` call — children inherit the same cap.
+     */
+    readonly maxSubflowDepth?: number;
+}
+export declare const DEFAULT_MAX_PARALLELISM = 8;
+/** Default cap on nested sub-flow depth. See `RunOptions.maxSubflowDepth`. */
+export declare const DEFAULT_MAX_SUBGRAPH_DEPTH = 10;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,6 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+export const DEFAULT_MAX_PARALLELISM = 8;
+/** Default cap on nested sub-flow depth. See `RunOptions.maxSubflowDepth`. */
+export const DEFAULT_MAX_SUBGRAPH_DEPTH = 10;
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC;AAqXjC,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,CAAC;AAEzC,8EAA8E;AAC9E,MAAM,CAAC,MAAM,0BAA0B,GAAG,EAAE,CAAC"}

package/dist/versioning.d.ts

@@ -0,0 +1,59 @@
+import type { Result } from '@kindgi/types';
+/**
+ * Payload versioning for the documents the runtime stores (journal
+ * payloads, run input / output, …).
+ *
+ * Every stored payload is a nested envelope `{ v: 1, doc: <content> }`.
+ * Wrapping under a dedicated `doc` key means the envelope's version
+ * marker cannot collide with any user field named `version`,
+ * `schemaVersion`, etc. Readers switch on `v` and return the inner `doc`,
+ * so consumer code sees the same content shape as if no envelope
+ * existed.
+ *
+ * Newer versions than this reader knows about are a hard error — a
+ * writer/reader skew would silently drop v2 data otherwise. No implicit
+ * versioning: every payload must carry an explicit envelope.
+ */
+export declare const CURRENT_KERNEL_PAYLOAD_VERSION = 1;
+/** Discriminated error surfaced when a stored payload's version exceeds the reader's. */
+export interface UnsupportedPayloadVersionError {
+    readonly code: 'unsupported-payload-version';
+    readonly message: string;
+    readonly version: number;
+    readonly currentVersion: number;
+}
+/** Emitted when a stored payload lacks the envelope entirely. */
+export interface MalformedEnvelopeError {
+    readonly code: 'malformed-envelope';
+    readonly message: string;
+}
+export type EnvelopeError = UnsupportedPayloadVersionError | MalformedEnvelopeError;
+/**
+ * Thrown by `*OrThrow` helpers when a stored payload can't be unwrapped.
+ * Catch at the operation boundary (e.g. `readJournal`) and surface
+ * as a KernelError.
+ */
+export declare class EnvelopeThrown extends Error {
+    readonly error: EnvelopeError;
+    constructor(error: EnvelopeError);
+}
+/**
+ * Wrap any value in the current-version envelope. The stored payload is
+ * always `{ v: 1, doc: value }` regardless of whether `value` is an
+ * object, array, primitive, or null.
+ */
+export declare function wrap<T>(value: T): {
+    readonly v: number;
+    readonly doc: T;
+};
+/**
+ * Unwrap a stored envelope and return the inner document. Handles:
+ *   - null / undefined: returned as-is (nothing was stored).
+ *   - `{ v: 1, doc: X }`: returns `X`.
+ *   - `{ v: N, doc: X }` with any other numeric N:
+ *     `unsupported-payload-version` error.
+ *   - Anything else: `malformed-envelope` error.
+ */
+export declare function unwrap<T = unknown>(raw: unknown): Result<T | null | undefined, EnvelopeError>;
+export declare function unwrapOrThrow<T = unknown>(raw: unknown): T | null | undefined;
+//# sourceMappingURL=versioning.d.ts.map

package/dist/versioning.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"versioning.d.ts","sourceRoot":"","sources":["../src/versioning.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAE5C;;;;;;;;;;;;;;GAcG;AAEH,eAAO,MAAM,8BAA8B,IAAI,CAAC;AAEhD,yFAAyF;AACzF,MAAM,WAAW,8BAA8B;IAC7C,QAAQ,CAAC,IAAI,EAAE,6BAA6B,CAAC;IAC7C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAED,iEAAiE;AACjE,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,IAAI,EAAE,oBAAoB,CAAC;IACpC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,MAAM,aAAa,GAAG,8BAA8B,GAAG,sBAAsB,CAAC;AAEpF;;;;GAIG;AACH,qBAAa,cAAe,SAAQ,KAAK;IACvC,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC;gBAClB,KAAK,EAAE,aAAa;CAKjC;AAED;;;;GAIG;AACH,wBAAgB,IAAI,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG;IAAE,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,CAAC,CAAA;CAAE,CAEzE;AAED;;;;;;;GAOG;AACH,wBAAgB,MAAM,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,OAAO,GAAG,MAAM,CAAC,CAAC,GAAG,IAAI,GAAG,SAAS,EAAE,aAAa,CAAC,CAiC7F;AAED,wBAAgB,aAAa,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,OAAO,GAAG,CAAC,GAAG,IAAI,GAAG,SAAS,CAI7E"}

package/dist/versioning.js

@@ -0,0 +1,89 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+/**
+ * Payload versioning for the documents the runtime stores (journal
+ * payloads, run input / output, …).
+ *
+ * Every stored payload is a nested envelope `{ v: 1, doc: <content> }`.
+ * Wrapping under a dedicated `doc` key means the envelope's version
+ * marker cannot collide with any user field named `version`,
+ * `schemaVersion`, etc. Readers switch on `v` and return the inner `doc`,
+ * so consumer code sees the same content shape as if no envelope
+ * existed.
+ *
+ * Newer versions than this reader knows about are a hard error — a
+ * writer/reader skew would silently drop v2 data otherwise. No implicit
+ * versioning: every payload must carry an explicit envelope.
+ */
+export const CURRENT_KERNEL_PAYLOAD_VERSION = 1;
+/**
+ * Thrown by `*OrThrow` helpers when a stored payload can't be unwrapped.
+ * Catch at the operation boundary (e.g. `readJournal`) and surface
+ * as a KernelError.
+ */
+export class EnvelopeThrown extends Error {
+    error;
+    constructor(error) {
+        super(error.message);
+        this.error = error;
+        this.name = 'EnvelopeThrown';
+    }
+}
+/**
+ * Wrap any value in the current-version envelope. The stored payload is
+ * always `{ v: 1, doc: value }` regardless of whether `value` is an
+ * object, array, primitive, or null.
+ */
+export function wrap(value) {
+    return { v: CURRENT_KERNEL_PAYLOAD_VERSION, doc: value };
+}
+/**
+ * Unwrap a stored envelope and return the inner document. Handles:
+ *   - null / undefined: returned as-is (nothing was stored).
+ *   - `{ v: 1, doc: X }`: returns `X`.
+ *   - `{ v: N, doc: X }` with any other numeric N:
+ *     `unsupported-payload-version` error.
+ *   - Anything else: `malformed-envelope` error.
+ */
+export function unwrap(raw) {
+    if (raw === null || raw === undefined)
+        return { kind: 'ok', value: raw };
+    if (typeof raw !== 'object' || Array.isArray(raw)) {
+        return {
+            kind: 'err',
+            error: {
+                code: 'malformed-envelope',
+                message: `Expected { v, doc } envelope, got ${typeof raw === 'object' ? 'array' : typeof raw}`,
+            },
+        };
+    }
+    const envelope = raw;
+    if (typeof envelope.v !== 'number' || !('doc' in envelope)) {
+        return {
+            kind: 'err',
+            error: {
+                code: 'malformed-envelope',
+                message: 'Payload is missing v or doc field',
+            },
+        };
+    }
+    if (envelope.v === CURRENT_KERNEL_PAYLOAD_VERSION) {
+        return { kind: 'ok', value: envelope.doc };
+    }
+    return {
+        kind: 'err',
+        error: {
+            code: 'unsupported-payload-version',
+            message: `Unsupported payload version ${envelope.v} (this reader handles version ${CURRENT_KERNEL_PAYLOAD_VERSION})`,
+            version: envelope.v,
+            currentVersion: CURRENT_KERNEL_PAYLOAD_VERSION,
+        },
+    };
+}
+export function unwrapOrThrow(raw) {
+    const r = unwrap(raw);
+    if (r.kind === 'err')
+        throw new EnvelopeThrown(r.error);
+    return r.value;
+}
+//# sourceMappingURL=versioning.js.map

package/dist/versioning.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"versioning.js","sourceRoot":"","sources":["../src/versioning.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC;AAIjC;;;;;;;;;;;;;;GAcG;AAEH,MAAM,CAAC,MAAM,8BAA8B,GAAG,CAAC,CAAC;AAkBhD;;;;GAIG;AACH,MAAM,OAAO,cAAe,SAAQ,KAAK;IAC9B,KAAK,CAAgB;IAC9B,YAAY,KAAoB;QAC9B,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QACrB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;IAC/B,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,UAAU,IAAI,CAAI,KAAQ;IAC9B,OAAO,EAAE,CAAC,EAAE,8BAA8B,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC;AAC3D,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,MAAM,CAAc,GAAY;IAC9C,IAAI,GAAG,KAAK,IAAI,IAAI,GAAG,KAAK,SAAS;QAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC;IACzE,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;QAClD,OAAO;YACL,IAAI,EAAE,KAAK;YACX,KAAK,EAAE;gBACL,IAAI,EAAE,oBAAoB;gBAC1B,OAAO,EAAE,qCAAqC,OAAO,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,GAAG,EAAE;aAC/F;SACF,CAAC;IACJ,CAAC;IACD,MAAM,QAAQ,GAAG,GAAuD,CAAC;IACzE,IAAI,OAAO,QAAQ,CAAC,CAAC,KAAK,QAAQ,IAAI,CAAC,CAAC,KAAK,IAAI,QAAQ,CAAC,EAAE,CAAC;QAC3D,OAAO;YACL,IAAI,EAAE,KAAK;YACX,KAAK,EAAE;gBACL,IAAI,EAAE,oBAAoB;gBAC1B,OAAO,EAAE,mCAAmC;aAC7C;SACF,CAAC;IACJ,CAAC;IACD,IAAI,QAAQ,CAAC,CAAC,KAAK,8BAA8B,EAAE,CAAC;QAClD,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,QAAQ,CAAC,GAAQ,EAAE,CAAC;IAClD,CAAC;IACD,OAAO;QACL,IAAI,EAAE,KAAK;QACX,KAAK,EAAE;YACL,IAAI,EAAE,6BAA6B;YACnC,OAAO,EAAE,+BAA+B,QAAQ,CAAC,CAAC,iCAAiC,8BAA8B,GAAG;YACpH,OAAO,EAAE,QAAQ,CAAC,CAAC;YACnB,cAAc,EAAE,8BAA8B;SAC/C;KACF,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,aAAa,CAAc,GAAY;IACrD,MAAM,CAAC,GAAG,MAAM,CAAI,GAAG,CAAC,CAAC;IACzB,IAAI,CAAC,CAAC,IAAI,KAAK,KAAK;QAAE,MAAM,IAAI,cAAc,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;IACxD,OAAO,CAAC,CAAC,KAAK,CAAC;AACjB,CAAC"}

package/package.json

@@ -1,7 +1,53 @@
 {
   "name": "@kindgi/runtime",
-  "version": "0.0.0-bootstrap.0",
-  "description": "Placeholder so a trusted publisher can be attached. Releases are published from https://github.com/kindgi/kindgi-sdk with provenance; use 0.1.0 or later.",
+  "version": "0.1.0",
+  "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": { "type": "git", "url": "git+https://github.com/kindgi/kindgi-sdk.git" }
-}
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kindgi/kindgi-sdk.git",
+    "directory": "packages/runtime"
+  },
+  "homepage": "https://github.com/kindgi/kindgi-sdk/tree/main/packages/runtime#readme",
+  "bugs": {
+    "url": "https://github.com/kindgi/kindgi-sdk/issues"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "dependencies": {
+    "@kindgi/authz": "0.1.0",
+    "@kindgi/flow": "0.1.0",
+    "@kindgi/handler": "0.1.0",
+    "@kindgi/types": "0.1.0"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.5",
+    "typescript": "^5.7.3",
+    "vitest": "^2.1.8"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --typecheck --typecheck.only --passWithNoTests",
+    "clean": "rm -rf dist *.tsbuildinfo"
+  }
+}