@h-rig/contracts 0.0.6-alpha.131 → 0.0.6-alpha.133

package/dist/src/kernel.d.ts

@@ -0,0 +1,238 @@
+import { Schema } from "effect";
+import { ResolvedPipeline, StageContext, StageDescriptor, StageMutation, StageResult, StageRunOutcome } from "./stage";
+export declare const CapabilityTag: Schema.Literals<readonly ["kernel", "journal", "stage-runner", "transport", "loader-policy"]>;
+export type CapabilityTag = typeof CapabilityTag.Type;
+export declare const CapabilityProviderRef: Schema.Struct<{
+    readonly capability: Schema.Literals<readonly ["kernel", "journal", "stage-runner", "transport", "loader-policy"]>;
+    readonly pluginId: Schema.Trim;
+}>;
+export type CapabilityProviderRef = typeof CapabilityProviderRef.Type;
+export declare const CapabilityReplacement: Schema.Struct<{
+    readonly capability: Schema.Literals<readonly ["kernel", "journal", "stage-runner", "transport", "loader-policy"]>;
+    readonly providerPluginId: Schema.Trim;
+}>;
+export type CapabilityReplacement = typeof CapabilityReplacement.Type;
+export declare const CapabilityReplacementSpec: Schema.Union<readonly [Schema.Struct<{
+    readonly capability: Schema.Literals<readonly ["kernel", "journal", "stage-runner", "transport", "loader-policy"]>;
+    readonly providerPluginId: Schema.Trim;
+}>, Schema.Trim]>;
+export type CapabilityReplacementSpec = typeof CapabilityReplacementSpec.Type;
+export declare const PluginMeta: Schema.Struct<{
+    readonly id: Schema.Trim;
+    readonly version: Schema.Trim;
+    readonly provides: Schema.$Array<Schema.Literals<readonly ["kernel", "journal", "stage-runner", "transport", "loader-policy"]>>;
+    readonly requires: Schema.optional<Schema.$Array<Schema.Literals<readonly ["kernel", "journal", "stage-runner", "transport", "loader-policy"]>>>;
+    readonly replaces: Schema.optional<Schema.$Array<Schema.Union<readonly [Schema.Struct<{
+        readonly capability: Schema.Literals<readonly ["kernel", "journal", "stage-runner", "transport", "loader-policy"]>;
+        readonly providerPluginId: Schema.Trim;
+    }>, Schema.Trim]>>>;
+}>;
+export type PluginMeta = typeof PluginMeta.Type;
+export declare const LoadedPluginDescriptor: Schema.Struct<{
+    readonly meta: Schema.Struct<{
+        readonly id: Schema.Trim;
+        readonly version: Schema.Trim;
+        readonly provides: Schema.$Array<Schema.Literals<readonly ["kernel", "journal", "stage-runner", "transport", "loader-policy"]>>;
+        readonly requires: Schema.optional<Schema.$Array<Schema.Literals<readonly ["kernel", "journal", "stage-runner", "transport", "loader-policy"]>>>;
+        readonly replaces: Schema.optional<Schema.$Array<Schema.Union<readonly [Schema.Struct<{
+            readonly capability: Schema.Literals<readonly ["kernel", "journal", "stage-runner", "transport", "loader-policy"]>;
+            readonly providerPluginId: Schema.Trim;
+        }>, Schema.Trim]>>>;
+    }>;
+    readonly provides: Schema.$Array<Schema.Literals<readonly ["kernel", "journal", "stage-runner", "transport", "loader-policy"]>>;
+    readonly contributes: Schema.Unknown;
+    readonly runtime: Schema.Unknown;
+}>;
+export type LoadedPluginDescriptor = typeof LoadedPluginDescriptor.Type;
+export declare const ProtectedStageGrant: Schema.Struct<{
+    readonly stageId: Schema.Trim;
+    readonly pluginId: Schema.Trim;
+    readonly operations: Schema.$Array<Schema.Literals<readonly ["remove", "replace"]>>;
+    readonly grantedBy: Schema.optional<Schema.Trim>;
+    readonly reason: Schema.optional<Schema.String>;
+}>;
+export type ProtectedStageGrant = typeof ProtectedStageGrant.Type;
+export declare const KernelReplacementGrant: Schema.Struct<{
+    readonly pluginId: Schema.Trim;
+    readonly grantedBy: Schema.optional<Schema.Trim>;
+    readonly reason: Schema.optional<Schema.String>;
+}>;
+export type KernelReplacementGrant = typeof KernelReplacementGrant.Type;
+export declare const CapabilityGrants: Schema.Struct<{
+    readonly capabilityPrecedence: Schema.optional<Schema.$Record<Schema.String, Schema.$Array<Schema.Trim>>>;
+    readonly protectedStageGrants: Schema.optional<Schema.$Array<Schema.Struct<{
+        readonly stageId: Schema.Trim;
+        readonly pluginId: Schema.Trim;
+        readonly operations: Schema.$Array<Schema.Literals<readonly ["remove", "replace"]>>;
+        readonly grantedBy: Schema.optional<Schema.Trim>;
+        readonly reason: Schema.optional<Schema.String>;
+    }>>>;
+    readonly kernelReplacementGrants: Schema.optional<Schema.$Array<Schema.Struct<{
+        readonly pluginId: Schema.Trim;
+        readonly grantedBy: Schema.optional<Schema.Trim>;
+        readonly reason: Schema.optional<Schema.String>;
+    }>>>;
+}>;
+export type CapabilityGrants = typeof CapabilityGrants.Type;
+export declare const KernelBootErrorCode: Schema.Literals<readonly ["BootIncoherent", "AmbiguousCapability", "MissingCapability", "ProtectedStageViolation", "KernelReplacementDenied", "PipelineUnresolvable"]>;
+export type KernelBootErrorCode = typeof KernelBootErrorCode.Type;
+export declare const KernelBootError: Schema.Struct<{
+    readonly code: Schema.Literals<readonly ["BootIncoherent", "AmbiguousCapability", "MissingCapability", "ProtectedStageViolation", "KernelReplacementDenied", "PipelineUnresolvable"]>;
+    readonly message: Schema.Trim;
+    readonly capability: Schema.optional<Schema.Literals<readonly ["kernel", "journal", "stage-runner", "transport", "loader-policy"]>>;
+    readonly stageId: Schema.optional<Schema.Trim>;
+    readonly pluginIds: Schema.optional<Schema.$Array<Schema.Trim>>;
+}>;
+export type KernelBootError = typeof KernelBootError.Type;
+export declare class BootIncoherent extends Error {
+    readonly code = "BootIncoherent";
+}
+export declare class AmbiguousCapability extends Error {
+    readonly code = "AmbiguousCapability";
+}
+export declare class MissingCapability extends Error {
+    readonly code = "MissingCapability";
+}
+export declare class ProtectedStageViolation extends Error {
+    readonly code = "ProtectedStageViolation";
+}
+export declare class KernelReplacementDenied extends Error {
+    readonly code = "KernelReplacementDenied";
+}
+export declare class PipelineUnresolvable extends Error {
+    readonly code = "PipelineUnresolvable";
+}
+export declare const CapabilityResolutionStatus: Schema.Literals<readonly ["resolved", "ambiguous", "missing", "replaced"]>;
+export type CapabilityResolutionStatus = typeof CapabilityResolutionStatus.Type;
+export declare const CapabilityResolutionRecord: Schema.Struct<{
+    readonly capability: Schema.Literals<readonly ["kernel", "journal", "stage-runner", "transport", "loader-policy"]>;
+    readonly status: Schema.Literals<readonly ["resolved", "ambiguous", "missing", "replaced"]>;
+    readonly selectedPluginId: Schema.NullOr<Schema.Trim>;
+    readonly candidatePluginIds: Schema.$Array<Schema.Trim>;
+    readonly precedenceUsed: Schema.Boolean;
+    readonly replacementUsed: Schema.optional<Schema.Struct<{
+        readonly capability: Schema.Literals<readonly ["kernel", "journal", "stage-runner", "transport", "loader-policy"]>;
+        readonly providerPluginId: Schema.Trim;
+    }>>;
+    readonly error: Schema.optional<Schema.String>;
+}>;
+export type CapabilityResolutionRecord = typeof CapabilityResolutionRecord.Type;
+export declare const KernelResolutionRecord: Schema.Struct<{
+    readonly resolvedAt: Schema.String;
+    readonly capabilities: Schema.$Array<Schema.Struct<{
+        readonly capability: Schema.Literals<readonly ["kernel", "journal", "stage-runner", "transport", "loader-policy"]>;
+        readonly status: Schema.Literals<readonly ["resolved", "ambiguous", "missing", "replaced"]>;
+        readonly selectedPluginId: Schema.NullOr<Schema.Trim>;
+        readonly candidatePluginIds: Schema.$Array<Schema.Trim>;
+        readonly precedenceUsed: Schema.Boolean;
+        readonly replacementUsed: Schema.optional<Schema.Struct<{
+            readonly capability: Schema.Literals<readonly ["kernel", "journal", "stage-runner", "transport", "loader-policy"]>;
+            readonly providerPluginId: Schema.Trim;
+        }>>;
+        readonly error: Schema.optional<Schema.String>;
+    }>>;
+    readonly pipeline: Schema.optional<Schema.Struct<{
+        readonly runId: Schema.optional<Schema.brand<Schema.Trim, "RunId">>;
+        readonly order: Schema.$Array<Schema.brand<Schema.Trim, "StageId">>;
+        readonly record: Schema.$Array<Schema.Struct<{
+            readonly stageId: Schema.brand<Schema.Trim, "StageId">;
+            readonly contributedBy: Schema.Trim;
+            readonly removedBy: Schema.optional<Schema.Trim>;
+            readonly replacedBy: Schema.optional<Schema.Trim>;
+            readonly wrappedBy: Schema.optional<Schema.$Array<Schema.Trim>>;
+            readonly droppedAnchors: Schema.optional<Schema.$Array<Schema.brand<Schema.Trim, "StageId">>>;
+            readonly isProtected: Schema.Boolean;
+        }>>;
+        readonly cycles: Schema.$Array<Schema.$Array<Schema.brand<Schema.Trim, "StageId">>>;
+        readonly grantUses: Schema.optional<Schema.$Array<Schema.Struct<{
+            readonly kind: Schema.Literals<readonly ["protected-stage", "kernel-replacement"]>;
+            readonly target: Schema.Trim;
+            readonly pluginId: Schema.Trim;
+        }>>>;
+        readonly resolvedAt: Schema.optional<Schema.String>;
+    }>>;
+}>;
+export type KernelResolutionRecord = typeof KernelResolutionRecord.Type;
+export declare const BootResultDescriptor: Schema.Struct<{
+    readonly kernelPluginId: Schema.Trim;
+    readonly pluginIds: Schema.$Array<Schema.Trim>;
+    readonly resolution: Schema.Struct<{
+        readonly resolvedAt: Schema.String;
+        readonly capabilities: Schema.$Array<Schema.Struct<{
+            readonly capability: Schema.Literals<readonly ["kernel", "journal", "stage-runner", "transport", "loader-policy"]>;
+            readonly status: Schema.Literals<readonly ["resolved", "ambiguous", "missing", "replaced"]>;
+            readonly selectedPluginId: Schema.NullOr<Schema.Trim>;
+            readonly candidatePluginIds: Schema.$Array<Schema.Trim>;
+            readonly precedenceUsed: Schema.Boolean;
+            readonly replacementUsed: Schema.optional<Schema.Struct<{
+                readonly capability: Schema.Literals<readonly ["kernel", "journal", "stage-runner", "transport", "loader-policy"]>;
+                readonly providerPluginId: Schema.Trim;
+            }>>;
+            readonly error: Schema.optional<Schema.String>;
+        }>>;
+        readonly pipeline: Schema.optional<Schema.Struct<{
+            readonly runId: Schema.optional<Schema.brand<Schema.Trim, "RunId">>;
+            readonly order: Schema.$Array<Schema.brand<Schema.Trim, "StageId">>;
+            readonly record: Schema.$Array<Schema.Struct<{
+                readonly stageId: Schema.brand<Schema.Trim, "StageId">;
+                readonly contributedBy: Schema.Trim;
+                readonly removedBy: Schema.optional<Schema.Trim>;
+                readonly replacedBy: Schema.optional<Schema.Trim>;
+                readonly wrappedBy: Schema.optional<Schema.$Array<Schema.Trim>>;
+                readonly droppedAnchors: Schema.optional<Schema.$Array<Schema.brand<Schema.Trim, "StageId">>>;
+                readonly isProtected: Schema.Boolean;
+            }>>;
+            readonly cycles: Schema.$Array<Schema.$Array<Schema.brand<Schema.Trim, "StageId">>>;
+            readonly grantUses: Schema.optional<Schema.$Array<Schema.Struct<{
+                readonly kind: Schema.Literals<readonly ["protected-stage", "kernel-replacement"]>;
+                readonly target: Schema.Trim;
+                readonly pluginId: Schema.Trim;
+            }>>>;
+            readonly resolvedAt: Schema.optional<Schema.String>;
+        }>>;
+    }>;
+}>;
+export type BootResultDescriptor = typeof BootResultDescriptor.Type;
+export declare const JournalEvent: Schema.Struct<{
+    readonly type: Schema.Trim;
+    readonly runId: Schema.optional<Schema.brand<Schema.Trim, "RunId">>;
+    readonly at: Schema.String;
+    readonly payload: Schema.Unknown;
+}>;
+export type JournalEvent = typeof JournalEvent.Type;
+export interface LoadedPlugin {
+    meta: PluginMeta;
+    provides: ReadonlySet<CapabilityTag>;
+    contributes: unknown;
+    runtime: unknown;
+}
+export interface JournalCapability {
+    append(event: unknown): Promise<void>;
+    recordPipeline(runId: string, pipeline: ResolvedPipeline): Promise<void>;
+    recordStageOutcome?(runId: string, outcome: StageRunOutcome): Promise<void>;
+    read(runId: string): Promise<readonly unknown[]>;
+}
+export interface StageRunnerCapability {
+    resolve(defaultStages: readonly StageDescriptor[], mutations: readonly StageMutation[], grants?: CapabilityGrants): ResolvedPipeline;
+    runPipeline(runId: string, resolved: ResolvedPipeline, ctx: StageContext): Promise<readonly StageRunOutcome[]>;
+}
+export interface TransportCapability {
+    dispatch(task: unknown, options?: unknown): Promise<string>;
+    attach?(runId: string): Promise<unknown>;
+    serve?(): Promise<void>;
+}
+export interface LoaderPolicyCapability {
+    resolveCapability(plugins: readonly PluginMeta[], capability: CapabilityTag, grants?: CapabilityGrants): CapabilityResolutionRecord;
+}
+export interface KernelCapability {
+    journal: JournalCapability;
+    stageRunner: StageRunnerCapability;
+    transport: TransportCapability;
+    loaderPolicy: LoaderPolicyCapability;
+    start(plugins: readonly unknown[]): Promise<void>;
+}
+export interface BootResult {
+    kernel: KernelCapability;
+    plugins: readonly LoadedPlugin[];
+}
+export type StageExecutor = (ctx: StageContext) => Promise<StageResult> | StageResult;

package/dist/src/kernel.js

@@ -0,0 +1,284 @@
+// @bun
+// packages/contracts/src/kernel.ts
+import { Schema as Schema3 } from "effect";
+
+// packages/contracts/src/baseSchemas.ts
+import { Schema } from "effect";
+var TrimmedString = Schema.Trim;
+var TrimmedNonEmptyString = TrimmedString.check(Schema.isNonEmpty());
+var NonNegativeInt = Schema.Int.check(Schema.isGreaterThanOrEqualTo(0));
+var PositiveInt = Schema.Int.check(Schema.isGreaterThanOrEqualTo(1));
+var IsoDateTime = Schema.String;
+var makeEntityId = (brand) => TrimmedNonEmptyString.pipe(Schema.brand(brand));
+var ThreadId = makeEntityId("ThreadId");
+var ProjectId = makeEntityId("ProjectId");
+var WorkspaceId = makeEntityId("WorkspaceId");
+var GraphId = makeEntityId("GraphId");
+var TaskId = makeEntityId("TaskId");
+var RunId = makeEntityId("RunId");
+var SafePathSegment = TrimmedNonEmptyString.check(Schema.isPattern(/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/)).pipe(Schema.brand("SafePathSegment"));
+var SafeRunId = TrimmedNonEmptyString.check(Schema.isPattern(/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/)).pipe(Schema.brand("SafeRunId"));
+var SafeGitRefComponent = TrimmedNonEmptyString.check(Schema.isPattern(/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/)).pipe(Schema.brand("SafeGitRefComponent"));
+var EngineRuntimeId = makeEntityId("EngineRuntimeId");
+var ConversationId = makeEntityId("ConversationId");
+var ActionId = makeEntityId("ActionId");
+var ArtifactId = makeEntityId("ArtifactId");
+var WorktreeId = makeEntityId("WorktreeId");
+var ValidationResultId = makeEntityId("ValidationResultId");
+var ReviewResultId = makeEntityId("ReviewResultId");
+var CommandId = makeEntityId("CommandId");
+var EventId = makeEntityId("EventId");
+var MessageId = makeEntityId("MessageId");
+var TurnId = makeEntityId("TurnId");
+var ProviderItemId = makeEntityId("ProviderItemId");
+var RuntimeSessionId = makeEntityId("RuntimeSessionId");
+var RuntimeItemId = makeEntityId("RuntimeItemId");
+var RuntimeRequestId = makeEntityId("RuntimeRequestId");
+var RuntimeTaskId = makeEntityId("RuntimeTaskId");
+var ApprovalRequestId = makeEntityId("ApprovalRequestId");
+var CheckpointRef = makeEntityId("CheckpointRef");
+var RemoteEndpointId = makeEntityId("RemoteEndpointId");
+
+// packages/contracts/src/stage.ts
+import { Schema as Schema2 } from "effect";
+var StageKind = Schema2.Literals(["transform", "gate", "observe"]);
+var StageId = TrimmedNonEmptyString.pipe(Schema2.brand("StageId"));
+var StageContext = Schema2.Struct({
+  runId: RunId,
+  taskId: Schema2.optional(Schema2.NullOr(TaskId)),
+  state: Schema2.Unknown,
+  metadata: Schema2.optional(Schema2.Record(Schema2.String, Schema2.Unknown))
+});
+var StageDescriptor = Schema2.Struct({
+  id: StageId,
+  kind: StageKind,
+  before: Schema2.optional(Schema2.Array(StageId)),
+  after: Schema2.optional(Schema2.Array(StageId)),
+  priority: Schema2.Number.pipe(Schema2.withDecodingDefault(() => 0)),
+  protected: Schema2.Boolean.pipe(Schema2.withDecodingDefault(() => false))
+});
+var StageContinueResult = Schema2.Struct({
+  kind: Schema2.Literal("continue"),
+  ctx: StageContext
+});
+var StageAllowResult = Schema2.Struct({
+  kind: Schema2.Literal("allow")
+});
+var StageBlockResult = Schema2.Struct({
+  kind: Schema2.Literal("block"),
+  reason: TrimmedNonEmptyString
+});
+var StageResult = Schema2.Union([
+  StageContinueResult,
+  StageAllowResult,
+  StageBlockResult
+]);
+var StageWrapperDescriptor = Schema2.Struct({
+  id: TrimmedNonEmptyString,
+  priority: Schema2.Number.pipe(Schema2.withDecodingDefault(() => 0))
+});
+var StageMutationOp = Schema2.Literals(["insert", "remove", "replace", "wrap", "reorder"]);
+var InsertStageMutation = Schema2.Struct({
+  op: Schema2.Literal("insert"),
+  stage: StageDescriptor,
+  contributedBy: Schema2.optional(TrimmedNonEmptyString)
+});
+var RemoveStageMutation = Schema2.Struct({
+  op: Schema2.Literal("remove"),
+  id: StageId,
+  contributedBy: Schema2.optional(TrimmedNonEmptyString)
+});
+var ReplaceStageMutation = Schema2.Struct({
+  op: Schema2.Literal("replace"),
+  id: StageId,
+  stage: StageDescriptor,
+  contributedBy: Schema2.optional(TrimmedNonEmptyString)
+});
+var WrapStageMutation = Schema2.Struct({
+  op: Schema2.Literal("wrap"),
+  id: StageId,
+  around: StageWrapperDescriptor,
+  contributedBy: Schema2.optional(TrimmedNonEmptyString)
+});
+var ReorderStageMutation = Schema2.Struct({
+  op: Schema2.Literal("reorder"),
+  id: StageId,
+  before: Schema2.optional(Schema2.Array(StageId)),
+  after: Schema2.optional(Schema2.Array(StageId)),
+  contributedBy: Schema2.optional(TrimmedNonEmptyString)
+});
+var StageMutation = Schema2.Union([
+  InsertStageMutation,
+  RemoveStageMutation,
+  ReplaceStageMutation,
+  WrapStageMutation,
+  ReorderStageMutation
+]);
+var ResolutionGrantUse = Schema2.Struct({
+  kind: Schema2.Literals(["protected-stage", "kernel-replacement"]),
+  target: TrimmedNonEmptyString,
+  pluginId: TrimmedNonEmptyString
+});
+var ResolutionRecordEntry = Schema2.Struct({
+  stageId: StageId,
+  contributedBy: TrimmedNonEmptyString,
+  removedBy: Schema2.optional(TrimmedNonEmptyString),
+  replacedBy: Schema2.optional(TrimmedNonEmptyString),
+  wrappedBy: Schema2.optional(Schema2.Array(TrimmedNonEmptyString)),
+  droppedAnchors: Schema2.optional(Schema2.Array(StageId)),
+  isProtected: Schema2.Boolean
+});
+var ResolvedPipeline = Schema2.Struct({
+  runId: Schema2.optional(RunId),
+  order: Schema2.Array(StageId),
+  record: Schema2.Array(ResolutionRecordEntry),
+  cycles: Schema2.Array(Schema2.Array(StageId)),
+  grantUses: Schema2.optional(Schema2.Array(ResolutionGrantUse)),
+  resolvedAt: Schema2.optional(IsoDateTime)
+});
+var StageRunOutcome = Schema2.Struct({
+  stageId: StageId,
+  result: StageResult,
+  startedAt: IsoDateTime,
+  finishedAt: IsoDateTime
+});
+
+// packages/contracts/src/kernel.ts
+var CapabilityTag = Schema3.Literals([
+  "kernel",
+  "journal",
+  "stage-runner",
+  "transport",
+  "loader-policy"
+]);
+var CapabilityProviderRef = Schema3.Struct({
+  capability: CapabilityTag,
+  pluginId: TrimmedNonEmptyString
+});
+var CapabilityReplacement = Schema3.Struct({
+  capability: CapabilityTag,
+  providerPluginId: TrimmedNonEmptyString
+});
+var CapabilityReplacementSpec = Schema3.Union([
+  CapabilityReplacement,
+  TrimmedNonEmptyString
+]);
+var PluginMeta = Schema3.Struct({
+  id: TrimmedNonEmptyString,
+  version: TrimmedNonEmptyString,
+  provides: Schema3.Array(CapabilityTag),
+  requires: Schema3.optional(Schema3.Array(CapabilityTag)),
+  replaces: Schema3.optional(Schema3.Array(CapabilityReplacementSpec))
+});
+var LoadedPluginDescriptor = Schema3.Struct({
+  meta: PluginMeta,
+  provides: Schema3.Array(CapabilityTag),
+  contributes: Schema3.Unknown,
+  runtime: Schema3.Unknown
+});
+var ProtectedStageGrant = Schema3.Struct({
+  stageId: TrimmedNonEmptyString,
+  pluginId: TrimmedNonEmptyString,
+  operations: Schema3.Array(Schema3.Literals(["remove", "replace"])),
+  grantedBy: Schema3.optional(TrimmedNonEmptyString),
+  reason: Schema3.optional(Schema3.String)
+});
+var KernelReplacementGrant = Schema3.Struct({
+  pluginId: TrimmedNonEmptyString,
+  grantedBy: Schema3.optional(TrimmedNonEmptyString),
+  reason: Schema3.optional(Schema3.String)
+});
+var CapabilityGrants = Schema3.Struct({
+  capabilityPrecedence: Schema3.optional(Schema3.Record(Schema3.String, Schema3.Array(TrimmedNonEmptyString))),
+  protectedStageGrants: Schema3.optional(Schema3.Array(ProtectedStageGrant)),
+  kernelReplacementGrants: Schema3.optional(Schema3.Array(KernelReplacementGrant))
+});
+var KernelBootErrorCode = Schema3.Literals([
+  "BootIncoherent",
+  "AmbiguousCapability",
+  "MissingCapability",
+  "ProtectedStageViolation",
+  "KernelReplacementDenied",
+  "PipelineUnresolvable"
+]);
+var KernelBootError = Schema3.Struct({
+  code: KernelBootErrorCode,
+  message: TrimmedNonEmptyString,
+  capability: Schema3.optional(CapabilityTag),
+  stageId: Schema3.optional(TrimmedNonEmptyString),
+  pluginIds: Schema3.optional(Schema3.Array(TrimmedNonEmptyString))
+});
+
+class BootIncoherent extends Error {
+  code = "BootIncoherent";
+}
+
+class AmbiguousCapability extends Error {
+  code = "AmbiguousCapability";
+}
+
+class MissingCapability extends Error {
+  code = "MissingCapability";
+}
+
+class ProtectedStageViolation extends Error {
+  code = "ProtectedStageViolation";
+}
+
+class KernelReplacementDenied extends Error {
+  code = "KernelReplacementDenied";
+}
+
+class PipelineUnresolvable extends Error {
+  code = "PipelineUnresolvable";
+}
+var CapabilityResolutionStatus = Schema3.Literals(["resolved", "ambiguous", "missing", "replaced"]);
+var CapabilityResolutionRecord = Schema3.Struct({
+  capability: CapabilityTag,
+  status: CapabilityResolutionStatus,
+  selectedPluginId: Schema3.NullOr(TrimmedNonEmptyString),
+  candidatePluginIds: Schema3.Array(TrimmedNonEmptyString),
+  precedenceUsed: Schema3.Boolean,
+  replacementUsed: Schema3.optional(CapabilityReplacement),
+  error: Schema3.optional(Schema3.String)
+});
+var KernelResolutionRecord = Schema3.Struct({
+  resolvedAt: IsoDateTime,
+  capabilities: Schema3.Array(CapabilityResolutionRecord),
+  pipeline: Schema3.optional(ResolvedPipeline)
+});
+var BootResultDescriptor = Schema3.Struct({
+  kernelPluginId: TrimmedNonEmptyString,
+  pluginIds: Schema3.Array(TrimmedNonEmptyString),
+  resolution: KernelResolutionRecord
+});
+var JournalEvent = Schema3.Struct({
+  type: TrimmedNonEmptyString,
+  runId: Schema3.optional(RunId),
+  at: IsoDateTime,
+  payload: Schema3.Unknown
+});
+export {
+  ProtectedStageViolation,
+  ProtectedStageGrant,
+  PluginMeta,
+  PipelineUnresolvable,
+  MissingCapability,
+  LoadedPluginDescriptor,
+  KernelResolutionRecord,
+  KernelReplacementGrant,
+  KernelReplacementDenied,
+  KernelBootErrorCode,
+  KernelBootError,
+  JournalEvent,
+  CapabilityTag,
+  CapabilityResolutionStatus,
+  CapabilityResolutionRecord,
+  CapabilityReplacementSpec,
+  CapabilityReplacement,
+  CapabilityProviderRef,
+  CapabilityGrants,
+  BootResultDescriptor,
+  BootIncoherent,
+  AmbiguousCapability
+};

package/dist/src/planning.d.ts

@@ -0,0 +1,64 @@
+import { Schema } from "effect";
+export declare const ClarificationStatus: Schema.Literals<readonly ["open", "resolved-from-code", "resolved-by-human", "deferred"]>;
+export type ClarificationStatus = typeof ClarificationStatus.Type;
+export declare const OpenQuestion: Schema.Struct<{
+    readonly id: Schema.Trim;
+    readonly question: Schema.Trim;
+    readonly status: Schema.Literals<readonly ["open", "resolved-from-code", "resolved-by-human", "deferred"]>;
+    readonly resolution: Schema.NullOr<Schema.String>;
+}>;
+export type OpenQuestion = typeof OpenQuestion.Type;
+export declare const UserStory: Schema.Struct<{
+    readonly id: Schema.Trim;
+    readonly title: Schema.Trim;
+    readonly priority: Schema.Int;
+}>;
+export type UserStory = typeof UserStory.Type;
+export declare const FunctionalRequirement: Schema.Struct<{
+    readonly id: Schema.Trim;
+    readonly text: Schema.Trim;
+}>;
+export type FunctionalRequirement = typeof FunctionalRequirement.Type;
+export declare const PlanTask: Schema.Struct<{
+    readonly localId: Schema.Trim;
+    readonly title: Schema.Trim;
+    readonly description: Schema.String;
+    readonly acceptance: Schema.$Array<Schema.String>;
+    readonly scope: Schema.$Array<Schema.Trim>;
+    readonly validationKeys: Schema.$Array<Schema.Trim>;
+    readonly dependsOn: Schema.$Array<Schema.Trim>;
+    readonly parent: Schema.NullOr<Schema.Trim>;
+    readonly parallelizable: Schema.Boolean;
+}>;
+export type PlanTask = typeof PlanTask.Type;
+export declare const PlanSpec: Schema.Struct<{
+    readonly prdTitle: Schema.Trim;
+    readonly userStories: Schema.$Array<Schema.Struct<{
+        readonly id: Schema.Trim;
+        readonly title: Schema.Trim;
+        readonly priority: Schema.Int;
+    }>>;
+    readonly functionalRequirements: Schema.$Array<Schema.Struct<{
+        readonly id: Schema.Trim;
+        readonly text: Schema.Trim;
+    }>>;
+    readonly openQuestions: Schema.$Array<Schema.Struct<{
+        readonly id: Schema.Trim;
+        readonly question: Schema.Trim;
+        readonly status: Schema.Literals<readonly ["open", "resolved-from-code", "resolved-by-human", "deferred"]>;
+        readonly resolution: Schema.NullOr<Schema.String>;
+    }>>;
+    readonly tasks: Schema.$Array<Schema.Struct<{
+        readonly localId: Schema.Trim;
+        readonly title: Schema.Trim;
+        readonly description: Schema.String;
+        readonly acceptance: Schema.$Array<Schema.String>;
+        readonly scope: Schema.$Array<Schema.Trim>;
+        readonly validationKeys: Schema.$Array<Schema.Trim>;
+        readonly dependsOn: Schema.$Array<Schema.Trim>;
+        readonly parent: Schema.NullOr<Schema.Trim>;
+        readonly parallelizable: Schema.Boolean;
+    }>>;
+    readonly generatedAt: Schema.String;
+}>;
+export type PlanSpec = typeof PlanSpec.Type;

package/dist/src/planning.js

@@ -0,0 +1,90 @@
+// @bun
+// packages/contracts/src/planning.ts
+import { Schema as Schema2 } from "effect";
+
+// packages/contracts/src/baseSchemas.ts
+import { Schema } from "effect";
+var TrimmedString = Schema.Trim;
+var TrimmedNonEmptyString = TrimmedString.check(Schema.isNonEmpty());
+var NonNegativeInt = Schema.Int.check(Schema.isGreaterThanOrEqualTo(0));
+var PositiveInt = Schema.Int.check(Schema.isGreaterThanOrEqualTo(1));
+var IsoDateTime = Schema.String;
+var makeEntityId = (brand) => TrimmedNonEmptyString.pipe(Schema.brand(brand));
+var ThreadId = makeEntityId("ThreadId");
+var ProjectId = makeEntityId("ProjectId");
+var WorkspaceId = makeEntityId("WorkspaceId");
+var GraphId = makeEntityId("GraphId");
+var TaskId = makeEntityId("TaskId");
+var RunId = makeEntityId("RunId");
+var SafePathSegment = TrimmedNonEmptyString.check(Schema.isPattern(/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/)).pipe(Schema.brand("SafePathSegment"));
+var SafeRunId = TrimmedNonEmptyString.check(Schema.isPattern(/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/)).pipe(Schema.brand("SafeRunId"));
+var SafeGitRefComponent = TrimmedNonEmptyString.check(Schema.isPattern(/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/)).pipe(Schema.brand("SafeGitRefComponent"));
+var EngineRuntimeId = makeEntityId("EngineRuntimeId");
+var ConversationId = makeEntityId("ConversationId");
+var ActionId = makeEntityId("ActionId");
+var ArtifactId = makeEntityId("ArtifactId");
+var WorktreeId = makeEntityId("WorktreeId");
+var ValidationResultId = makeEntityId("ValidationResultId");
+var ReviewResultId = makeEntityId("ReviewResultId");
+var CommandId = makeEntityId("CommandId");
+var EventId = makeEntityId("EventId");
+var MessageId = makeEntityId("MessageId");
+var TurnId = makeEntityId("TurnId");
+var ProviderItemId = makeEntityId("ProviderItemId");
+var RuntimeSessionId = makeEntityId("RuntimeSessionId");
+var RuntimeItemId = makeEntityId("RuntimeItemId");
+var RuntimeRequestId = makeEntityId("RuntimeRequestId");
+var RuntimeTaskId = makeEntityId("RuntimeTaskId");
+var ApprovalRequestId = makeEntityId("ApprovalRequestId");
+var CheckpointRef = makeEntityId("CheckpointRef");
+var RemoteEndpointId = makeEntityId("RemoteEndpointId");
+
+// packages/contracts/src/planning.ts
+var ClarificationStatus = Schema2.Literals([
+  "open",
+  "resolved-from-code",
+  "resolved-by-human",
+  "deferred"
+]);
+var OpenQuestion = Schema2.Struct({
+  id: TrimmedNonEmptyString,
+  question: TrimmedNonEmptyString,
+  status: ClarificationStatus,
+  resolution: Schema2.NullOr(Schema2.String)
+});
+var UserStory = Schema2.Struct({
+  id: TrimmedNonEmptyString,
+  title: TrimmedNonEmptyString,
+  priority: PositiveInt
+});
+var FunctionalRequirement = Schema2.Struct({
+  id: TrimmedNonEmptyString,
+  text: TrimmedNonEmptyString
+});
+var PlanTask = Schema2.Struct({
+  localId: TrimmedNonEmptyString,
+  title: TrimmedNonEmptyString,
+  description: Schema2.String,
+  acceptance: Schema2.Array(Schema2.String),
+  scope: Schema2.Array(TrimmedNonEmptyString),
+  validationKeys: Schema2.Array(TrimmedNonEmptyString),
+  dependsOn: Schema2.Array(TrimmedNonEmptyString),
+  parent: Schema2.NullOr(TrimmedNonEmptyString),
+  parallelizable: Schema2.Boolean
+});
+var PlanSpec = Schema2.Struct({
+  prdTitle: TrimmedNonEmptyString,
+  userStories: Schema2.Array(UserStory),
+  functionalRequirements: Schema2.Array(FunctionalRequirement),
+  openQuestions: Schema2.Array(OpenQuestion),
+  tasks: Schema2.Array(PlanTask),
+  generatedAt: IsoDateTime
+});
+export {
+  UserStory,
+  PlanTask,
+  PlanSpec,
+  OpenQuestion,
+  FunctionalRequirement,
+  ClarificationStatus
+};