@noetaris/harness 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 NOETARIS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,219 @@
+declare const _fieldType: unique symbol;
+type FieldDefinition<T> = {
+    readonly [_fieldType]: T;
+    readonly default?: () => T;
+    readonly reduce?: (current: T, update: T) => T;
+};
+type StateFromSchema<S> = {
+    [K in keyof S]: S[K] extends FieldDefinition<infer T> ? T : never;
+};
+type FieldOptions<T> = {
+    default?: () => T;
+    reduce?: (current: T, update: T) => T;
+};
+declare function field<T>(options?: FieldOptions<T>): FieldDefinition<T>;
+
+declare const REQUIRED_TAG: "__noetaris_required__";
+declare const RUNTIME_TAG: "__noetaris_runtime__";
+type RequiredMarker = {
+    readonly _tag: typeof REQUIRED_TAG;
+};
+type RuntimeMarker = {
+    readonly _tag: typeof RUNTIME_TAG;
+};
+type DeepWithMarkers<T> = T extends (...args: any[]) => any ? T | RequiredMarker | RuntimeMarker : T extends object ? {
+    [K in keyof T]: DeepWithMarkers<T[K]> | RequiredMarker | RuntimeMarker;
+} | RequiredMarker | RuntimeMarker : T | RequiredMarker | RuntimeMarker;
+declare function required(): RequiredMarker;
+declare function runtime(): RuntimeMarker;
+declare function isRequiredMarker(value: unknown): value is RequiredMarker;
+declare function isRuntimeMarker(value: unknown): value is RuntimeMarker;
+
+/** Framework fields injected into every step function's state argument. */
+interface FrameworkState {
+    readonly $error: Error | null;
+    readonly $interrupt: {
+        readonly interruptId: string;
+        readonly prompt: unknown;
+        readonly response?: unknown;
+    } | null;
+}
+/** The full state type visible inside step functions: user state + framework fields. */
+type StepState<S> = S & FrameworkState;
+/**
+ * State transformer. Receives the full step state and ctx; returns a partial update
+ * of user-defined state fields only (framework-reserved fields are excluded from return).
+ * May be async.
+ */
+type RunFn<S, Ctx> = (state: StepState<S>, ctx: Ctx & {
+    readonly sessionId: string;
+    readonly interrupt: (prompt: unknown, id?: string) => Promise<unknown>;
+    readonly emit: (name: string, payload?: unknown) => void;
+}) => Promise<Partial<Omit<S, '$error' | '$interrupt'>>> | Partial<Omit<S, '$error' | '$interrupt'>>;
+/**
+ * Pure signal emitter. Receives step state without $error — the route is not called on the error
+ * path unless the step opts in via `optin: '$error'` in the step config. Synchronous by design.
+ * No ctx — pure read only.
+ */
+type RouteFn<S> = (state: S & Omit<FrameworkState, '$error'>) => string;
+/**
+ * Pure signal emitter for error-aware steps (optin: '$error').
+ * Receives the full step state including $error — the executor calls this on both the success
+ * and error paths. Declare `optin: '$error'` in the step config to use this variant.
+ */
+type ErrorAwareRouteFn<S> = (state: StepState<S>) => string;
+/**
+ * Options passed to `.step(name, options)`. At least one of `run` or `route` must be set.
+ *
+ * Two variants:
+ * - Without `optin`: route receives state without `$error` (TypeScript-enforced). On error,
+ *   the framework falls through to `l.onError()` or pauses with `signal: "$error"` automatically.
+ * - With `optin: '$error'`: route receives the full state including `$error`, and the executor
+ *   calls route on the error path. Use this when the step's route needs to inspect or handle errors.
+ */
+type StepOptions<S, Ctx> = {
+    readonly optin: '$error';
+    run?: RunFn<S, Ctx>;
+    route?: ErrorAwareRouteFn<S>;
+} | {
+    readonly optin?: undefined;
+    run?: RunFn<S, Ctx>;
+    route?: RouteFn<S>;
+};
+/**
+ * Fluent chain returned by .on(signal). Caller must call either .to(step) or .end()
+ * to complete the transition declaration.
+ */
+interface OnChain<S, Ctx> {
+    /** Route the signal to the named step. Returns the builder for further chaining. */
+    to(step: string): LoopBuilder<S, Ctx>;
+    /** Exit the loop when this signal is emitted. Returns the builder for further chaining. */
+    end(): LoopBuilder<S, Ctx>;
+}
+/**
+ * The DSL object passed as `l` to the h.loop(l => ...) builder lambda.
+ * All methods mutate internal state and return `this` for chaining.
+ */
+interface LoopBuilder<S, Ctx> {
+    /** Mark the loop as having a declared entry. The first .step() called after .start() is the entry. */
+    start(): LoopBuilder<S, Ctx>;
+    /** Declare a step. At least one of run or route must be set (validated later by LoopValidator). */
+    step(name: string, options: StepOptions<S, Ctx>): LoopBuilder<S, Ctx>;
+    /**
+     * Begin a signal transition declaration. Must be called immediately after .step() or after
+     * a previous .on().to() or .on().end() chain (attaches to the most recently declared step).
+     */
+    on(signal: string): OnChain<S, Ctx>;
+    /**
+     * Declare an explicit unconditional next target for the most recently declared step.
+     * Mutually exclusive with route (validated by LoopValidator).
+     */
+    next(name: string): LoopBuilder<S, Ctx>;
+    /**
+     * Declare a loop-level fallback error step. Any step whose run throws and whose
+     * route does not handle $error will route to this step instead of pausing the session.
+     * Only one onError target per loop; multiple calls replace the previous target (last wins).
+     */
+    onError(step: string): LoopBuilder<S, Ctx>;
+}
+
+type Harness<Ctx, State, Req extends keyof Ctx = never, Run extends keyof Ctx = never> = {
+    provide<K extends keyof Ctx>(key: K, value: RequiredMarker): Harness<Ctx, State, Req | K, Run>;
+    provide<K extends keyof Ctx>(key: K, value: RuntimeMarker): Harness<Ctx, State, Req, Run | K>;
+    provide<K extends keyof Ctx>(key: K, value: DeepWithMarkers<Ctx[K]>): Harness<Ctx, State, Req, Run>;
+    store(stores: DeepWithMarkers<{
+        session?: unknown;
+    } & Record<string, unknown>>): Harness<Ctx, State, Req, Run>;
+    loop(builder: (l: LoopBuilder<State, Ctx>) => void): Harness<Ctx, State, Req, Run>;
+};
+declare function createHarness<Ctx = any>(): <S extends object = {}>(// any: allows createHarness() without an explicit Ctx type parameter
+stateSchema?: S) => Harness<Ctx, StateFromSchema<S>>;
+
+interface SessionStore {
+    load(sessionId: string): Promise<StoredRun | null>;
+    save(sessionId: string, run: StoredRun): Promise<void>;
+    loadHistory?(sessionId: string): Promise<StoredRun[]>;
+    branch?(sessionId: string, runId: string): Promise<string>;
+}
+interface StoredRun {
+    readonly runId: string;
+    readonly sessionId: string;
+    readonly startedAt: string;
+    readonly settledAt: string;
+    readonly phase: 'paused' | 'completed';
+    readonly initialState: Record<string, unknown>;
+    readonly finalState: Record<string, unknown>;
+    readonly signal?: string;
+    readonly step?: string;
+}
+type SessionPhase = {
+    readonly phase: 'fresh';
+} | {
+    readonly phase: 'in-flight';
+    readonly step: null;
+} | {
+    readonly phase: 'paused';
+    readonly signal?: string;
+    readonly step: string;
+} | {
+    readonly phase: 'completed';
+    readonly signal?: string;
+};
+
+interface RunOutcome {
+    readonly state: Record<string, unknown>;
+    readonly signal: string | null;
+}
+interface RunHandle extends PromiseLike<RunOutcome> {
+    /** Cancel the in-flight run at the next safe point between steps. Idempotent. */
+    stop(): void;
+    /**
+     * Provide a response to a pending ctx.interrupt() call.
+     * Returns a new RunHandle for the resumed execution.
+     * Stub in F8 — implemented in F9.
+     */
+    resume(response: unknown, interruptId: string): RunHandle;
+    /** The session identity for this run. */
+    readonly sessionId: string;
+    /**
+     * The name of the step currently executing in this process.
+     * null before the first step runs, after execution settles, and always when inspected cross-process.
+     */
+    readonly currentStep: string | null;
+}
+
+interface Agent {
+    /**
+     * Start a new run. Returns a RunHandle synchronously before execution begins.
+     */
+    run(initialState: Record<string, unknown>, resources: Record<string, unknown>): RunHandle;
+    /**
+     * Cross-process entry point for responding to a pending interrupt.
+     * Returns a RunHandle synchronously; the execution promise performs the resume.
+     */
+    resume(response: unknown, sessionId: string, interruptId: string): RunHandle;
+    /**
+     * Query the session store for the current phase of a session.
+     */
+    status(sessionId: string): Promise<SessionPhase>;
+}
+declare function createAgent<Ctx, State, Req extends keyof Ctx, Run extends keyof Ctx>(h: Harness<Ctx, State, Req, Run>, slots: Pick<Ctx, Req>): Agent;
+
+declare class NoInterruptError extends Error {
+    constructor();
+}
+
+declare class SessionInFlightError extends Error {
+    readonly sessionId: string;
+    constructor(sessionId: string);
+}
+declare class SessionPendingInterruptError extends Error {
+    readonly sessionId: string;
+    constructor(sessionId: string);
+}
+declare class StoreLoadError extends Error {
+    readonly cause: unknown;
+    constructor(cause: unknown);
+}
+
+export { type Agent, type DeepWithMarkers, type FieldDefinition, type Harness, NoInterruptError, REQUIRED_TAG, RUNTIME_TAG, type RequiredMarker, type RuntimeMarker, SessionInFlightError, SessionPendingInterruptError, type SessionStore, type StateFromSchema, StoreLoadError, type StoredRun, createAgent, createHarness, field, isRequiredMarker, isRuntimeMarker, required, runtime };