@kitman-sh/sdk 0.0.0-stage → 0.7.0

package/types/packages/sdk/src/build/index.d.ts

@@ -0,0 +1,45 @@
+import { PackageDeclarations } from '../../../core/src/package-declarations';
+import * as Effect from 'effect/Effect';
+import * as FileSystem from 'effect/FileSystem';
+import * as Path from 'effect/Path';
+import * as Schema from 'effect/Schema';
+import { ChildProcessSpawner } from 'effect/process';
+import type { LoopCheckError } from '../loop/check';
+import type { ManifestInvalid } from '../loop/define';
+declare const DependencyInstallFailed_base: Schema.Class<DependencyInstallFailed, Schema.TaggedStruct<"DependencyInstallFailed", {
+    readonly reason: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+export declare class DependencyInstallFailed extends DependencyInstallFailed_base {
+    get message(): string;
+}
+declare const BundleFailed_base: Schema.Class<BundleFailed, Schema.TaggedStruct<"BundleFailed", {
+    readonly reason: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+export declare class BundleFailed extends BundleFailed_base {
+    get message(): string;
+}
+declare const DeclarationsInvalid_base: Schema.Class<DeclarationsInvalid, Schema.TaggedStruct<"DeclarationsInvalid", {
+    readonly reason: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+export declare class DeclarationsInvalid extends DeclarationsInvalid_base {
+    get message(): string;
+}
+export type PackageBuildError = DependencyInstallFailed | BundleFailed | DeclarationsInvalid | ManifestInvalid | LoopCheckError;
+export type PackageProvenance = {
+    readonly repository?: string;
+    readonly commit?: string;
+    readonly clean: boolean;
+};
+export type PackageBuild = {
+    /** From `package.json`. */
+    readonly name: string;
+    /** One module that runs with nothing but `bun`: the program host, the config, the SDK, Effect and every dependency. */
+    readonly bundle: Uint8Array;
+    readonly digest: string;
+    readonly declarations: PackageDeclarations;
+    readonly protocolVersion: number;
+    readonly provenance: PackageProvenance;
+};
+/** Builds the Package in `directory` into one bundle and its declarations; dependencies install with lifecycle scripts off. */
+export declare const buildPackage: (directory: string) => Effect.Effect<PackageBuild, PackageBuildError, FileSystem.FileSystem | Path.Path | ChildProcessSpawner.ChildProcessSpawner>;
+export {};

package/types/packages/sdk/src/loop/activities.d.ts

@@ -0,0 +1,187 @@
+import * as Context from 'effect/Context';
+import * as Effect from 'effect/Effect';
+import * as Schema from 'effect/Schema';
+import { StepFailed } from './steps';
+/** The Run's ChangeRequest, from its branch to its base branch. */
+export declare const ChangeRequestRequest: Schema.Struct<{
+    readonly title: Schema.String;
+    readonly body: Schema.String;
+    /** A RepoBinding: opens from the Run's integration branch on it, into its base branch, instead. */
+    readonly integration: Schema.optional<Schema.String>;
+}>;
+export declare const ChangeRequestResult: Schema.Struct<{
+    readonly id: Schema.String;
+    readonly number: Schema.String;
+    readonly url: Schema.String;
+}>;
+export type ChangeRequestResult = typeof ChangeRequestResult.Type;
+export declare const WriteBackMilestones: readonly ['started', 'change_request_opened', 'merged', 'failed'];
+/** A Run milestone for the Run's Task, which moves it to the state its Team maps the milestone to. */
+export declare const WriteBackRequest: Schema.Struct<{
+    readonly milestone: Schema.optional<Schema.Literals<readonly ["started", "change_request_opened", "merged", "failed"]>>;
+    readonly changeRequestUrl: Schema.optional<Schema.String>;
+}>;
+/** A document stored in Kitman with the Run, such as a plan, findings or a conclusion; later Runs retrieve it. */
+export declare const ArtifactRequest: Schema.Struct<{
+    readonly kind: Schema.String;
+    readonly title: Schema.String;
+    readonly text: Schema.String;
+    readonly data: Schema.optional<Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+}>;
+export declare const ArtifactResult: Schema.Struct<{
+    readonly artifactId: Schema.String;
+}>;
+/** A thread entry on the Run's Task; given an artifact, it links to it. */
+export declare const NoteRequest: Schema.Struct<{
+    readonly text: Schema.String;
+    readonly artifactId: Schema.optional<Schema.String>;
+}>;
+export declare const CreateTasksRequest: Schema.Struct<{
+    readonly tickets: Schema.$Array<Schema.Struct<{
+        readonly key: Schema.String;
+        readonly title: Schema.String;
+        readonly body: Schema.String;
+        readonly acceptanceCriteria: Schema.$Array<Schema.String>;
+        readonly repoBindingId: Schema.optional<Schema.String>;
+        readonly blockedBy: Schema.$Array<Schema.String>;
+        readonly outcome: Schema.optional<Schema.Literals<readonly ["feature", "bug", "refactor", "investigation", "docs", "migration"]>>;
+    }>>;
+}>;
+/** The Task made for each ticket, by ticket key. */
+export declare const CreateTasksResult: Schema.Struct<{
+    readonly tasks: Schema.$Array<Schema.Struct<{
+        readonly key: Schema.String;
+        readonly taskId: Schema.String;
+    }>>;
+}>;
+/** The Project's default RepoBinding when left out. */
+export declare const IntegrationBranchRequest: Schema.Struct<{
+    readonly repoBindingId: Schema.optional<Schema.String>;
+}>;
+export declare const IntegrationBranch: Schema.Struct<{
+    readonly repoBindingId: Schema.String;
+    readonly branch: Schema.String;
+    /** The branch head now. */
+    readonly revision: Schema.String;
+}>;
+export type IntegrationBranch = typeof IntegrationBranch.Type;
+export declare const MergeChangeRequestRequest: Schema.Struct<{
+    readonly changeRequestId: Schema.String;
+}>;
+export declare const MergeResult: Schema.Union<readonly [Schema.Struct<{
+    readonly status: Schema.Literal<"merged">;
+    readonly revision: Schema.String;
+}>, Schema.Struct<{
+    readonly status: Schema.Literal<"conflict">;
+}>]>;
+export type MergeResult = typeof MergeResult.Type;
+/** A comment on a ChangeRequest, which need not be the Run's own. */
+export declare const CommentRequest: Schema.Struct<{
+    readonly changeRequestId: Schema.String;
+    readonly body: Schema.String;
+}>;
+/** Tags `revision`, the Run's base branch head when left out, and publishes the release with its notes. */
+export declare const ReleaseRequest: Schema.Struct<{
+    readonly tag: Schema.String;
+    readonly revision: Schema.optional<Schema.String>;
+    readonly title: Schema.String;
+    readonly notes: Schema.String;
+}>;
+export declare const ReleaseResult: Schema.Struct<{
+    readonly tag: Schema.String;
+    readonly revision: Schema.String;
+    readonly url: Schema.String;
+}>;
+export type ReleaseResult = typeof ReleaseResult.Type;
+declare const ChangeRequestActivity_base: Context.ServiceClass<ChangeRequestActivity, "@kitman-sh/sdk/loop/ChangeRequestActivity", {
+    /** A Run has one ChangeRequest: it opens once, and a later Step updates it. */
+    readonly run: (request: typeof ChangeRequestRequest.Type, step: string) => Effect.Effect<ChangeRequestResult, StepFailed>;
+}>;
+/** Opens or updates the Run's ChangeRequest. */
+export declare class ChangeRequestActivity extends ChangeRequestActivity_base {
+}
+declare const WriteBackActivity_base: Context.ServiceClass<WriteBackActivity, "@kitman-sh/sdk/loop/WriteBackActivity", {
+    readonly run: (request: typeof WriteBackRequest.Type, step: string) => Effect.Effect<void, StepFailed>;
+}>;
+/** Gives the Run's Task a milestone of the Run's. */
+export declare class WriteBackActivity extends WriteBackActivity_base {
+}
+declare const ArtifactActivity_base: Context.ServiceClass<ArtifactActivity, "@kitman-sh/sdk/loop/ArtifactActivity", {
+    /** `step` names the Step storing it; a Step stores one artifact, however often it runs. */
+    readonly run: (request: typeof ArtifactRequest.Type, step: string) => Effect.Effect<typeof ArtifactResult.Type, StepFailed>;
+}>;
+/** Stores a Run artifact in Kitman, indexed for later Runs' ContextPacks and search. */
+export declare class ArtifactActivity extends ArtifactActivity_base {
+}
+declare const NoteActivity_base: Context.ServiceClass<NoteActivity, "@kitman-sh/sdk/loop/NoteActivity", {
+    readonly run: (request: typeof NoteRequest.Type, step: string) => Effect.Effect<void, StepFailed>;
+}>;
+/** Adds an entry to the thread of the Run's Task. */
+export declare class NoteActivity extends NoteActivity_base {
+}
+declare const CommentActivity_base: Context.ServiceClass<CommentActivity, "@kitman-sh/sdk/loop/CommentActivity", {
+    readonly run: (request: typeof CommentRequest.Type, step: string) => Effect.Effect<void, StepFailed>;
+}>;
+/** Posts a comment on a ChangeRequest through Kitman's external-effect ledger; a Step posts once. */
+export declare class CommentActivity extends CommentActivity_base {
+}
+declare const CreateTasksActivity_base: Context.ServiceClass<CreateTasksActivity, "@kitman-sh/sdk/loop/CreateTasksActivity", {
+    /** A Step makes each ticket's Task once. */
+    readonly run: (request: typeof CreateTasksRequest.Type, step: string) => Effect.Effect<typeof CreateTasksResult.Type, StepFailed>;
+}>;
+/** Makes a Task for each plan ticket, with the plan ticket as its origin and its blockers as TaskDependencies. */
+export declare class CreateTasksActivity extends CreateTasksActivity_base {
+}
+declare const IntegrationBranchActivity_base: Context.ServiceClass<IntegrationBranchActivity, "@kitman-sh/sdk/loop/IntegrationBranchActivity", {
+    readonly run: (request: typeof IntegrationBranchRequest.Type, step: string) => Effect.Effect<IntegrationBranch, StepFailed>;
+}>;
+/** The Run's integration branch on a repository, made from its base branch the first time. */
+export declare class IntegrationBranchActivity extends IntegrationBranchActivity_base {
+}
+declare const MergeChangeRequestActivity_base: Context.ServiceClass<MergeChangeRequestActivity, "@kitman-sh/sdk/loop/MergeChangeRequestActivity", {
+    readonly run: (request: typeof MergeChangeRequestRequest.Type, step: string) => Effect.Effect<MergeResult, StepFailed>;
+}>;
+/** Merges a ChangeRequest into its target branch through the external-effect ledger; a Step merges once. */
+export declare class MergeChangeRequestActivity extends MergeChangeRequestActivity_base {
+}
+declare const ReleaseActivity_base: Context.ServiceClass<ReleaseActivity, "@kitman-sh/sdk/loop/ReleaseActivity", {
+    readonly run: (request: typeof ReleaseRequest.Type, step: string) => Effect.Effect<ReleaseResult, StepFailed>;
+}>;
+/** Tags and publishes a release on the Run's repository through the external-effect ledger; a Step releases once. */
+export declare class ReleaseActivity extends ReleaseActivity_base {
+}
+export declare const changeRequest: (name: string, request: typeof ChangeRequestRequest.Type) => Effect.Effect<{
+    readonly id: string;
+    readonly number: string;
+    readonly url: string;
+}, import("./steps").CapabilityDenied | import("./steps").DuplicateStep | StepFailed, ChangeRequestActivity | import("./steps").LoopRun | import("effect/workflow/WorkflowEngine").WorkflowEngine | import("effect/workflow/WorkflowEngine").WorkflowInstance>;
+export declare const writeBack: (name: string, request: typeof WriteBackRequest.Type) => Effect.Effect<void, import("./steps").CapabilityDenied | import("./steps").DuplicateStep | StepFailed, import("./steps").LoopRun | import("effect/workflow/WorkflowEngine").WorkflowEngine | import("effect/workflow/WorkflowEngine").WorkflowInstance | WriteBackActivity>;
+export declare const artifact: (name: string, request: typeof ArtifactRequest.Type) => Effect.Effect<{
+    readonly artifactId: string;
+}, import("./steps").CapabilityDenied | import("./steps").DuplicateStep | StepFailed, ArtifactActivity | import("./steps").LoopRun | import("effect/workflow/WorkflowEngine").WorkflowEngine | import("effect/workflow/WorkflowEngine").WorkflowInstance>;
+export declare const note: (name: string, request: typeof NoteRequest.Type) => Effect.Effect<void, import("./steps").CapabilityDenied | import("./steps").DuplicateStep | StepFailed, import("./steps").LoopRun | NoteActivity | import("effect/workflow/WorkflowEngine").WorkflowEngine | import("effect/workflow/WorkflowEngine").WorkflowInstance>;
+export declare const comment: (name: string, request: typeof CommentRequest.Type) => Effect.Effect<void, import("./steps").CapabilityDenied | import("./steps").DuplicateStep | StepFailed, CommentActivity | import("./steps").LoopRun | import("effect/workflow/WorkflowEngine").WorkflowEngine | import("effect/workflow/WorkflowEngine").WorkflowInstance>;
+export declare const createTasks: (name: string, request: typeof CreateTasksRequest.Type) => Effect.Effect<{
+    readonly tasks: readonly {
+        readonly key: string;
+        readonly taskId: string;
+    }[];
+}, import("./steps").CapabilityDenied | import("./steps").DuplicateStep | StepFailed, CreateTasksActivity | import("./steps").LoopRun | import("effect/workflow/WorkflowEngine").WorkflowEngine | import("effect/workflow/WorkflowEngine").WorkflowInstance>;
+/** Its head is read when the Step runs, so a later Step with another name sees what was merged since. */
+export declare const integrationBranch: (name: string, request: typeof IntegrationBranchRequest.Type) => Effect.Effect<{
+    readonly repoBindingId: string;
+    readonly branch: string;
+    readonly revision: string;
+}, import("./steps").CapabilityDenied | import("./steps").DuplicateStep | StepFailed, IntegrationBranchActivity | import("./steps").LoopRun | import("effect/workflow/WorkflowEngine").WorkflowEngine | import("effect/workflow/WorkflowEngine").WorkflowInstance>;
+export declare const mergeChangeRequest: (name: string, request: typeof MergeChangeRequestRequest.Type) => Effect.Effect<{
+    readonly status: "merged";
+    readonly revision: string;
+} | {
+    readonly status: "conflict";
+}, import("./steps").CapabilityDenied | import("./steps").DuplicateStep | StepFailed, import("./steps").LoopRun | MergeChangeRequestActivity | import("effect/workflow/WorkflowEngine").WorkflowEngine | import("effect/workflow/WorkflowEngine").WorkflowInstance>;
+export declare const release: (name: string, request: typeof ReleaseRequest.Type) => Effect.Effect<{
+    readonly tag: string;
+    readonly revision: string;
+    readonly url: string;
+}, import("./steps").CapabilityDenied | import("./steps").DuplicateStep | StepFailed, import("./steps").LoopRun | ReleaseActivity | import("effect/workflow/WorkflowEngine").WorkflowEngine | import("effect/workflow/WorkflowEngine").WorkflowInstance>;
+export {};

package/types/packages/sdk/src/loop/check.d.ts

@@ -0,0 +1,39 @@
+import * as Cause from 'effect/Cause';
+import * as Effect from 'effect/Effect';
+import * as Schema from 'effect/Schema';
+import type { LoopDefinition } from './define';
+import { type LoopCheck } from './test-loop';
+declare const CheckFailed_base: Schema.Class<CheckFailed, Schema.TaggedStruct<"CheckFailed", {
+    readonly loop: Schema.String;
+    readonly check: Schema.String;
+    readonly reason: Schema.String;
+}>, Cause.YieldableError>;
+export declare class CheckFailed extends CheckFailed_base {
+    get detail(): string;
+    get message(): string;
+}
+declare const StepNamedTwice_base: Schema.Class<StepNamedTwice, Schema.TaggedStruct<"StepNamedTwice", {
+    readonly loop: Schema.String;
+    readonly check: Schema.String;
+    readonly step: Schema.String;
+}>, Cause.YieldableError>;
+export declare class StepNamedTwice extends StepNamedTwice_base {
+    get detail(): string;
+    get message(): string;
+}
+declare const ReplayDiverged_base: Schema.Class<ReplayDiverged, Schema.TaggedStruct<"ReplayDiverged", {
+    readonly loop: Schema.String;
+    readonly check: Schema.String;
+    readonly first: Schema.$Array<Schema.String>;
+    readonly replay: Schema.$Array<Schema.String>;
+    readonly rerun: Schema.$Array<Schema.String>;
+}>, Cause.YieldableError>;
+export declare class ReplayDiverged extends ReplayDiverged_base {
+    get detail(): string;
+    get message(): string;
+}
+export declare const LoopCheckError: Schema.Union<readonly [typeof CheckFailed, typeof StepNamedTwice, typeof ReplayDiverged]>;
+export type LoopCheckError = typeof LoopCheckError.Type;
+/** Runs a check twice, the second time from the first run's journal; the replay must take the same Steps and rerun no Activity. */
+export declare const checkLoop: (loop: LoopDefinition<unknown, unknown, unknown>, check: LoopCheck) => Effect.Effect<void, LoopCheckError>;
+export {};

package/types/packages/sdk/src/loop/config.d.ts

@@ -0,0 +1,68 @@
+import type { KitAssignmentDeclaration, KitInstallationDeclaration, ScheduleDeclaration } from '../../../core/src/package-declarations';
+import type { LoopDefinition } from './define';
+/** Agent instructions inline, or a Markdown file in the Package's repository, read at build. */
+export type AgentInstructions = string | {
+    readonly file: string;
+};
+export type AgentConfig = {
+    /** The Agent this one extends. */
+    readonly extends?: string;
+    readonly instructions?: AgentInstructions;
+    readonly harness?: string;
+    readonly model?: string;
+    /** How hard its harness thinks; a harness without the control ignores it. */
+    readonly effort?: 'low' | 'medium' | 'high' | 'xhigh';
+    /** Kit references. */
+    readonly kits?: readonly string[];
+    /** Hosts its sandboxed Steps may reach beyond the defaults, or `open` for an Agent that browses. */
+    readonly network?: {
+        readonly hosts: readonly string[];
+    } | 'open';
+    /** Runs its Steps only on Runners that run agents in docker, for services or a project image. */
+    readonly sandbox?: 'docker';
+};
+/** A Kit written from the Package's files: its context, and skill directories each holding a `SKILL.md`. */
+export type AuthoredKitConfig = {
+    readonly name: string;
+    readonly kind?: 'technology' | 'brand' | 'domain' | 'process' | 'other';
+    readonly description?: string;
+    readonly context: AgentInstructions;
+    /** Skill directories in the repository; each is named after its directory. */
+    readonly skills?: readonly string[];
+};
+/** An authored Kit, a Marketplace Kit to install, or where a Kit applies. */
+export type KitConfig = AuthoredKitConfig | KitInstallationDeclaration | KitAssignmentDeclaration;
+export type PackageLoop = LoopDefinition<unknown, unknown, unknown>;
+/** A Package's `kitman.config.ts` default export. */
+export type PackageConfig = {
+    readonly loops: readonly PackageLoop[];
+    readonly agents?: {
+        readonly [id: string]: AgentConfig;
+    };
+    readonly schedules?: {
+        readonly [key: string]: ScheduleDeclaration;
+    };
+    readonly kits?: {
+        readonly [key: string]: KitConfig;
+    };
+};
+/** Each element a Loop, whatever its Input, Output and error types. */
+type Loops<L extends readonly unknown[]> = {
+    readonly [K in keyof L]: L[K] extends LoopDefinition<infer In, infer Out, infer E> ? LoopDefinition<In, Out, E> : never;
+};
+/** Declares a Package: its Loops, and its Agents keyed by id. */
+export declare const defineConfig: <const L extends readonly unknown[]>(config: {
+    readonly loops: L & Loops<L>;
+    readonly agents?: {
+        readonly [id: string]: AgentConfig;
+    };
+    /** Recurring starts of a Loop, keyed; the Package owns each Schedule it declares. */
+    readonly schedules?: {
+        readonly [key: string]: ScheduleDeclaration;
+    };
+    /** Kits, keyed; only a Workspace Package may declare them. */
+    readonly kits?: {
+        readonly [key: string]: KitConfig;
+    };
+}) => PackageConfig;
+export {};

package/types/packages/sdk/src/loop/define.d.ts

@@ -0,0 +1,76 @@
+import { LoopCapabilities, type LoopManifest } from '../../../core/src/package-declarations';
+import * as Effect from 'effect/Effect';
+import * as Schema from 'effect/Schema';
+import type { WorkflowEngine } from 'effect/workflow';
+import type { LoopHost, LoopRun } from './steps';
+import type { LoopCheck } from './test-loop';
+import type { ArtifactActivity, ChangeRequestActivity, CommentActivity, CreateTasksActivity, IntegrationBranchActivity, MergeChangeRequestActivity, NoteActivity, ReleaseActivity, WriteBackActivity } from './activities';
+export { LoopCapabilities, type LoopManifest };
+/** What a Loop's program may ask Kitman for; the control plane checks each request against them. */
+export type LoopCapability = (typeof LoopCapabilities)[number];
+export declare const LoopOutcome: Schema.Literals<readonly ["feature", "bug", "refactor", "investigation", "docs", "migration"]>;
+export type LoopOutcome = typeof LoopOutcome.Type;
+export type LoopCheckout = 'none' | 'read' | 'write';
+type EventFilterValue = string | number | boolean | null;
+/** Matched by the control plane against Event payload paths: a value, or any of several. */
+export type EventFilter = {
+    readonly [path: string]: EventFilterValue | readonly EventFilterValue[];
+};
+/** Starts a Run on a matching Event, binding Event payload paths into the Loop Input. */
+export type WhenClause = {
+    readonly event: string;
+    readonly filter?: EventFilter;
+    readonly input: {
+        readonly [inputField: string]: string;
+    };
+};
+/** An action shown on a settled Run: start another Loop. */
+export type LoopOffer = {
+    readonly id: string;
+    readonly title: string;
+    readonly loop: string;
+};
+/** The services a Loop's program runs with; a Runner or `testLoop` provides them. */
+export type LoopServices = LoopRun | LoopHost | ChangeRequestActivity | WriteBackActivity | ArtifactActivity | NoteActivity | CommentActivity | CreateTasksActivity | IntegrationBranchActivity | MergeChangeRequestActivity | ReleaseActivity | WorkflowEngine.WorkflowEngine | WorkflowEngine.WorkflowInstance;
+/** A schema a Loop can decode and encode with no services. */
+export type LoopSchema<T> = Schema.Codec<T, unknown>;
+export type LoopDefinition<In, Out, E> = {
+    readonly id: string;
+    readonly title: string;
+    readonly input: LoopSchema<In>;
+    readonly output: LoopSchema<Out>;
+    readonly outcome?: LoopOutcome;
+    /** Agent ids by role; `agentWork` names a role. */
+    readonly agents: {
+        readonly [role: string]: string;
+    };
+    readonly checkout: LoopCheckout;
+    readonly when?: readonly WhenClause[];
+    readonly offers?: readonly LoopOffer[];
+    readonly capabilities: readonly LoopCapability[];
+    /** The Secrets the program reads with `Config.Redacted`, and `agentWork` may put into a Step's sandbox. */
+    readonly secrets?: readonly string[];
+    /**
+     * The hosts the program calls besides Kitman, or `open` for any; a shared Runner refuses the rest. An `open` Loop
+     * runs only on a Runner with `docker`, or a personal Runner.
+     */
+    readonly network?: {
+        readonly hosts: readonly string[];
+    } | 'open';
+    readonly run: (input: In) => Effect.Effect<Out, E, LoopServices>;
+    /** Scripts a build runs twice, the second time from the journal; not part of the manifest. */
+    readonly checks?: readonly LoopCheck[];
+};
+/** A Loop module's default export. The definition keeps its shape, so a fork spreads it. */
+export declare const defineLoop: <In, Out, E>(definition: LoopDefinition<In, Out, E>) => LoopDefinition<In, Out, E>;
+declare const ManifestInvalid_base: Schema.Class<ManifestInvalid, Schema.TaggedStruct<"ManifestInvalid", {
+    readonly loop: Schema.String;
+    readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+export declare class ManifestInvalid extends ManifestInvalid_base {
+}
+export declare const jsonSchemaOf: <T>(loop: string, schema: LoopSchema<T>) => Effect.Effect<{
+    readonly [x: string]: Schema.Json;
+}, ManifestInvalid, never>;
+/** The data the control plane reads from a Loop, made without calling `run`. */
+export declare const loopManifest: <In, Out, E>(definition: LoopDefinition<In, Out, E>) => Effect.Effect<LoopManifest, ManifestInvalid>;

package/types/packages/sdk/src/loop/evidence.d.ts

@@ -0,0 +1,66 @@
+import * as Schema from 'effect/Schema';
+import type { LoopOutcome } from './define';
+import type { ScopeJudgement } from './review';
+/** One approved verification's result at a tree, as a Runner recorded it. */
+export declare const EvidenceCheck: Schema.Struct<{
+    readonly name: Schema.String;
+    readonly command: Schema.String;
+    readonly status: Schema.Literals<readonly ["passed", "failed"]>;
+    /** It also fails on the default branch's head, so the Run did not cause it. */
+    readonly preExisting: Schema.Boolean;
+    readonly durationMs: Schema.Finite;
+    readonly evidenceId: Schema.String;
+}>;
+export type EvidenceCheck = typeof EvidenceCheck.Type;
+/** Evidence for a revision; `tree` is its git tree id, and the evidence holds for any revision with that tree. */
+export declare const VerifyResult: Schema.Struct<{
+    readonly revision: Schema.String;
+    readonly tree: Schema.String;
+    /** Every check passed or already failed on the default branch. */
+    readonly passed: Schema.Boolean;
+    readonly checks: Schema.$Array<Schema.Struct<{
+        readonly name: Schema.String;
+        readonly command: Schema.String;
+        readonly status: Schema.Literals<readonly ["passed", "failed"]>;
+        /** It also fails on the default branch's head, so the Run did not cause it. */
+        readonly preExisting: Schema.Boolean;
+        readonly durationMs: Schema.Finite;
+        readonly evidenceId: Schema.String;
+    }>>;
+}>;
+export type VerifyResult = typeof VerifyResult.Type;
+/** What closes a Run, by its Outcome; `none` is a Run with no Outcome. */
+export declare const OutcomeTable: {
+    readonly feature: 'Approved verifications pass on the head tree, and review says the scope was met';
+    readonly bug: 'A reproducing check fails on the base and passes on the head';
+    readonly refactor: 'Approved verifications pass on both base and head';
+    readonly investigation: 'A conclusion Output with its sources; no patch needed';
+    readonly docs: 'The documented commands run';
+    readonly migration: 'A rollback check passes';
+    readonly none: 'Only the approved verifications';
+};
+export type EvidenceGateInput = {
+    readonly outcome?: LoopOutcome;
+    readonly head?: VerifyResult;
+    readonly base?: VerifyResult;
+    /** The reviewer's scope judgement; absent when no reviewer judged it, which never reads as met. */
+    readonly review?: ScopeJudgement;
+    /** The check that reproduces a bug. */
+    readonly reproducing?: string;
+    readonly conclusion?: {
+        readonly text: string;
+        readonly sources: readonly string[];
+    };
+    /** The checks that run the documented commands. */
+    readonly documented?: readonly string[];
+    /** The check that rolls a migration back. */
+    readonly rollback?: string;
+};
+export type EvidenceVerdict = {
+    readonly settled: true;
+} | {
+    readonly settled: false;
+    readonly reasons: readonly string[];
+};
+/** Whether the Run's evidence closes its Outcome, per `OutcomeTable`; claims in Outputs never count. */
+export declare const evidenceGate: (input: EvidenceGateInput) => EvidenceVerdict;

package/types/packages/sdk/src/loop/index.d.ts

@@ -0,0 +1,9 @@
+export * from './define';
+export * from './steps';
+export * from './activities';
+export * from './test-loop';
+export * from './evidence';
+export * from './review';
+export * from './plan';
+export * from './check';
+export * from './config';

package/types/packages/sdk/src/loop/plan.d.ts

@@ -0,0 +1,43 @@
+import * as Effect from 'effect/Effect';
+import * as Schema from 'effect/Schema';
+/** One unit of a plan, which Implement now turns into a Task and builds. */
+export declare const PlanTicket: Schema.Struct<{
+    /** Short and unique within the plan; blockers name it. */
+    readonly key: Schema.String;
+    readonly title: Schema.String;
+    readonly body: Schema.String;
+    readonly acceptanceCriteria: Schema.$Array<Schema.String>;
+    /** The repository it changes; the Project's default when left out. */
+    readonly repoBindingId: Schema.optional<Schema.String>;
+    /** Keys of the tickets that must be built first. */
+    readonly blockedBy: Schema.$Array<Schema.String>;
+    /** The kind of change; its Task gets the first Task Type with this Outcome. */
+    readonly outcome: Schema.optional<Schema.Literals<readonly ["feature", "bug", "refactor", "investigation", "docs", "migration"]>>;
+}>;
+export type PlanTicket = typeof PlanTicket.Type;
+/** A plan's tickets; a blocker must name another ticket, and no tickets may block each other in a cycle. */
+export declare const PlanTickets: Schema.$Array<Schema.Struct<{
+    /** Short and unique within the plan; blockers name it. */
+    readonly key: Schema.String;
+    readonly title: Schema.String;
+    readonly body: Schema.String;
+    readonly acceptanceCriteria: Schema.$Array<Schema.String>;
+    /** The repository it changes; the Project's default when left out. */
+    readonly repoBindingId: Schema.optional<Schema.String>;
+    /** Keys of the tickets that must be built first. */
+    readonly blockedBy: Schema.$Array<Schema.String>;
+    /** The kind of change; its Task gets the first Task Type with this Outcome. */
+    readonly outcome: Schema.optional<Schema.Literals<readonly ["feature", "bug", "refactor", "investigation", "docs", "migration"]>>;
+}>>;
+declare const BlockingCycle_base: Schema.Class<BlockingCycle, Schema.TaggedStruct<"BlockingCycle", {
+    readonly tickets: Schema.$Array<Schema.String>;
+}>, import("effect/Cause").YieldableError>;
+export declare class BlockingCycle extends BlockingCycle_base {
+    get message(): string;
+}
+/**
+ * Orders tickets into waves: a ticket is in the wave after its last blocker's, and each wave is grouped by
+ * RepoBinding. Every ticket in a wave can be built at once.
+ */
+export declare const planWaves: (tickets: readonly PlanTicket[]) => Effect.Effect<readonly PlanTicket[][], BlockingCycle>;
+export {};

package/types/packages/sdk/src/loop/review.d.ts

@@ -0,0 +1,86 @@
+import * as Schema from 'effect/Schema';
+export declare const Severity: Schema.Literals<readonly ["blocker", "major", "minor"]>;
+export type Severity = typeof Severity.Type;
+/** What one reviewer seat found. */
+export declare const Finding: Schema.Struct<{
+    readonly severity: Schema.Literals<readonly ["blocker", "major", "minor"]>;
+    readonly file: Schema.String;
+    readonly line: Schema.Int;
+    readonly detail: Schema.String;
+}>;
+export type Finding = typeof Finding.Type;
+/** A finding after the panel's findings are merged; `id` is its file and line. */
+export declare const MergedFinding: Schema.Struct<{
+    readonly severity: Schema.Literals<readonly ["blocker", "major", "minor"]>;
+    readonly file: Schema.String;
+    readonly line: Schema.Int;
+    readonly detail: Schema.String;
+    readonly id: Schema.String;
+    readonly seats: Schema.$Array<Schema.String>;
+}>;
+export type MergedFinding = typeof MergedFinding.Type;
+export declare const Rebuttal: Schema.Struct<{
+    readonly findingId: Schema.String;
+    readonly reason: Schema.String;
+}>;
+export type Rebuttal = typeof Rebuttal.Type;
+export declare const RebuttalVerdict: Schema.Struct<{
+    readonly findingId: Schema.String;
+    readonly accepted: Schema.Boolean;
+}>;
+export type RebuttalVerdict = typeof RebuttalVerdict.Type;
+/** Whether a change does what its Task asks; `unmet` names each criterion or part of the description not done. */
+export declare const ScopeJudgement: Schema.Struct<{
+    readonly met: Schema.Boolean;
+    readonly unmet: Schema.$Array<Schema.String>;
+}>;
+export type ScopeJudgement = typeof ScopeJudgement.Type;
+export type Disputed = {
+    readonly finding: MergedFinding;
+    readonly rebuttal: Rebuttal;
+};
+export declare const isBlocking: (finding: Pick<Finding, 'severity'>) => boolean;
+/** One finding per file and line; the worst severity's detail wins, and every seat that raised it is kept. */
+export declare const mergeFindings: (bySeat: {
+    readonly [seat: string]: readonly Finding[];
+}) => readonly MergedFinding[];
+export declare const splitDisputed: (findings: readonly MergedFinding[], rebuttals: readonly Rebuttal[]) => {
+    disputed: Disputed[];
+    undisputed: {
+        readonly severity: "blocker" | "major" | "minor";
+        readonly file: string;
+        readonly line: number;
+        readonly detail: string;
+        readonly id: string;
+        readonly seats: readonly string[];
+    }[];
+};
+export type SettledRound = {
+    /** Findings still to fix. */
+    readonly open: readonly MergedFinding[];
+    /** Rebutted, and the reviewers accepted the rebuttal. */
+    readonly withdrawn: readonly Disputed[];
+    /** Rebutted, and the reviewers did not accept the rebuttal. */
+    readonly standing: readonly Disputed[];
+};
+/** A rebutted finding is withdrawn only when every verdict on it accepts the rebuttal. */
+export declare const settleRound: (round: {
+    readonly findings: readonly MergedFinding[];
+    readonly rebuttals: readonly Rebuttal[];
+    readonly verdicts: readonly RebuttalVerdict[];
+}) => SettledRound;
+export type RallyStopReason = 'settled' | 'dispute_stands' | 'findings_returned' | 'round_cap';
+export type RallyDecision = {
+    readonly stop: false;
+} | {
+    readonly stop: true;
+    readonly reason: RallyStopReason;
+    readonly unsettled: readonly string[];
+};
+/** Whether the rally ends after this round; `previous` is the last round's blocking finding ids. */
+export declare const rallyStop: (input: {
+    readonly round: number;
+    readonly maxRounds: number;
+    readonly settled: SettledRound;
+    readonly previous?: readonly string[];
+}) => RallyDecision;