@humwick/server 0.130.1 → 0.130.3

package/node_modules/@humwick/kernel/contract.ts

@@ -1,572 +0,0 @@
-// #2666: direct module imports must initialize schema extensions before defineModule callers run.
-import "./openapi-init";
-import type * as z from "zod";
-import { assertValidManifest } from "./manifest-validation";
-import type { MessageAuthorityParticipant } from "./message-authority";
-
-declare const ScopeBrand: unique symbol;
-declare const ModuleDefinitionBrand: unique symbol;
-
-/** Kernel-minted owning scope. Modules may carry it but cannot construct one. */
-export type Scope = string & { readonly [ScopeBrand]: true };
-
-/** Flat, transport-independent authorization vocabulary. */
-export type Grant = `${string}:${"read" | "write" | "admin"}` | `command:${string}`;
-
-/**
- * Server-resolved creator attributes the host attaches to a principal so a module can FREEZE a
- * durable effect's create-time identity snapshot (P2-7, #1409) under the authenticated creator's
- * REAL reach — never a client-named one. The kernel treats every field as OPAQUE: `scopes` are the
- * creator's transport-layer scopes (e.g. `message:send`, which the flat {@link Grant} grammar cannot
- * spell) and `constraints` is an untyped blob (cwdPrefixes etc.) the host later reconstructs into a
- * token. Because this rides the {@link InvocationIdentity} the TRUSTED host binding builds — not the
- * client-facing op input — a client cannot supply or widen it. Absent for callers that mint no
- * durable effects (the common case); modules must fall back to `grants`/defaults when it is missing.
- */
-export interface ResolvedIdentity {
-  /** The creator's actor kind (e.g. `component`, `provider`, `system`) — cosmetic identity metadata. */
-  readonly kind?: string;
-  /** The creator's REAL transport scopes, carried verbatim so a durable send authorizes under
-   *  `message:send` (which is not a {@link Grant}). Frozen into `createdByScopes`. */
-  readonly scopes?: readonly string[];
-  /** The creator token's opaque constraint blob (cwd/agent axes). SERVER-resolved; frozen into
-   *  `createdByConstraints` so the fire-time authz gate binds to the creator's real constraint. */
-  readonly constraints?: Readonly<Record<string, unknown>>;
-}
-
-/** The sole identity shape visible to modules. */
-export interface Principal {
-  readonly actor: string;
-  readonly scope: Scope;
-  readonly grants: ReadonlySet<Grant>;
-  /** Opaque server-resolved creator attributes for durable-effect identity freezing (P2-7). The
-   *  host attaches it from the authenticated token via the trusted invocation identity; absent for
-   *  ordinary callers. See {@link ResolvedIdentity}. */
-  readonly resolvedIdentity?: ResolvedIdentity;
-}
-
-export type EventName = `${string}.${string}`;
-export type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "OPTIONS" | "HEAD";
-export type ConfigLayer = "defaults" | "instance" | "host" | "tenant" | "user";
-export type StepName = string;
-export type JsonPrimitive = string | number | boolean | null;
-export type JsonValue = JsonPrimitive | readonly JsonValue[] | { readonly [key: string]: JsonValue };
-
-type Schema = z.ZodType;
-type ObjectSchema = z.ZodObject<any>;
-type SchemaInput<S> = S extends z.ZodType ? z.input<S> : never;
-type SchemaOutput<S> = S extends z.ZodType ? z.output<S> : never;
-type RecordValue<R, K> = R extends Record<PropertyKey, unknown> ? R[K & keyof R] : never;
-
-export interface TraceContext {
-  readonly traceId: string;
-  readonly spanId: string;
-  child(name: string): TraceContext;
-}
-
-export interface Disposable {
-  dispose(): void;
-}
-
-export interface Clock {
-  now(): number;
-  sleep(ms: number): Promise<void>;
-  every(ms: number, fn: () => void): Disposable;
-}
-
-export interface Rng {
-  uuid(): string;
-  random(): number;
-  jitter(baseMs: number, spread: number): number;
-}
-
-/** Outbound HTTP is the only module-visible transport. */
-export interface Transport {
-  fetch(url: string, init?: RequestInit): Promise<Response>;
-}
-
-export interface Logger {
-  debug(message: string, fields?: Readonly<Record<string, unknown>>): void;
-  info(message: string, fields?: Readonly<Record<string, unknown>>): void;
-  warn(message: string, fields?: Readonly<Record<string, unknown>>): void;
-  error(message: string, fields?: Readonly<Record<string, unknown>>): void;
-}
-
-export interface ConfigDecl<S extends ObjectSchema = ObjectSchema> {
-  schema: S;
-  env?: Partial<Record<keyof z.output<S>, string>>;
-  overridableAt?: Partial<Record<keyof z.output<S>, readonly ConfigLayer[]>>;
-}
-
-export type ResolvedConfig<D> = D extends ConfigDecl<infer S>
-  ? Readonly<z.output<S>>
-  : Readonly<Record<never, never>>;
-
-export interface EntityRef {
-  module: string;
-  entity: string;
-}
-
-export interface EntityDecl<S extends ObjectSchema = ObjectSchema> {
-  schema: S;
-  key?: keyof z.output<S>;
-  indexes?: ReadonlyArray<keyof z.output<S> | readonly (keyof z.output<S>)[]>;
-  references?: Partial<Record<keyof z.output<S>, EntityRef>>;
-  retention?: { ttlDays?: number; ttlField?: keyof z.output<S> };
-  audit?: boolean;
-}
-
-type EntityValue<D> = D extends EntityDecl<infer S> ? z.output<S> : never;
-type EntityInput<D> = D extends EntityDecl<infer S> ? z.input<S> : never;
-type EntityKey<D> = D extends EntityDecl<infer S>
-  ? D["key"] extends keyof z.output<S>
-    ? z.output<S>[D["key"]]
-    : "id" extends keyof z.output<S>
-      ? z.output<S>["id"]
-      : unknown
-  : never;
-
-export interface EntityListOptions<V> {
-  limit?: number;
-  cursor?: string;
-  where?: Partial<V>;
-}
-
-export interface EntityPage<V> {
-  items: readonly V[];
-  /** Opaque continuation token for the next page. Absent when this is the final page. */
-  cursor?: string;
-}
-
-export interface EntityStore<D extends EntityDecl = EntityDecl> {
-  get(key: EntityKey<D>): Promise<EntityValue<D> | undefined>;
-  list(options?: EntityListOptions<EntityValue<D>>): Promise<EntityPage<EntityValue<D>>>;
-  create(value: EntityInput<D>): Promise<EntityValue<D>>;
-  update(key: EntityKey<D>, patch: Partial<EntityInput<D>>): Promise<EntityValue<D>>;
-  delete(key: EntityKey<D>): Promise<boolean>;
-}
-
-export type EntityStores<E> = E extends Record<string, EntityDecl>
-  ? { readonly [K in keyof E]: EntityStore<E[K]> }
-  : Readonly<Record<never, never>>;
-
-export interface EventWriter<E> {
-  emit<N extends keyof E & EventName>(name: N, payload: SchemaInput<RecordValue<E, N>>): Promise<void>;
-}
-
-export interface WorkflowStartOptions {
-  idempotencyKey: string;
-  /** How the instance SEED commits, relative to the caller's own commit scope.
-   *
-   *  Omitted (the ratified default): the seed commits in its OWN transaction immediately and the
-   *  drive runs inline — `start` returns the driven run. A crash after `start` returns leaves a
-   *  durable instance regardless of what the caller does next.
-   *
-   *  `"op-commit"` (T-0 hardening, #1409 finding 1): ONLY valid inside an op handler. The seed is
-   *  BUFFERED and executes INSIDE the op's atomic entity+event commit — after the entity flush, in
-   *  the same SQLite transaction — so an op that fails its optimistic-version CAS (or throws, or
-   *  fails output validation) rolls the instance seed back WITH its entities and events: no orphaned
-   *  workflow can survive an op that did not commit. The drive runs after the op commits (a drive
-   *  failure leaves a durable `pending` instance the recovery pass converges — the op itself has
-   *  already succeeded). The returned {@link WorkflowRun} is a PROVISIONAL projection: the live run
-   *  when the idempotency key already names an instance, else a `pending` stub whose id is the id
-   *  the commit will seed (a concurrent same-key seed between handler and commit may supersede it).
-   *  Outside an op invocation (a step body, a standalone client) this mode fails closed. */
-  enlist?: "op-commit";
-}
-
-export type WorkflowStatusName = "pending" | "running" | "sleeping" | "waiting" | "done" | "failed" | "canceled";
-
-export interface WorkflowRun<Output = unknown> {
-  readonly id: string;
-  readonly status: WorkflowStatusName | `step:${string}`;
-  readonly attempts: number;
-  readonly createdAt: number;
-  readonly updatedAt: number;
-  readonly output?: Output;
-  readonly error?: string;
-}
-
-type WorkflowInput<D> = D extends { input: infer In extends Schema } ? SchemaInput<In> : never;
-
-export interface WorkflowClient<W> {
-  start<N extends keyof W & string>(name: N, input: WorkflowInput<RecordValue<W, N>>, options: WorkflowStartOptions): Promise<WorkflowRun>;
-  status(id: string): Promise<WorkflowRun | undefined>;
-  cancel(id: string): Promise<boolean>;
-  /** Inside an op invocation this is enlisted in the op commit; elsewhere it commits immediately. */
-  control?(operation: "cancel" | "fail" | "reopen", id: string, failure?: JsonValue): Promise<boolean>;
-}
-
-export type HostCommandStatus = "queued" | "sent" | "executing" | "done" | "failed";
-
-export interface HostCommandRun<Out = unknown> {
-  readonly id: string;
-  readonly status: HostCommandStatus;
-  readonly result?: Out;
-  readonly error?: string;
-}
-
-type CommandInput<D> = D extends { input: infer In extends Schema } ? SchemaInput<In> : never;
-type CommandOutput<D> = D extends { result: infer Out extends Schema } ? SchemaOutput<Out> : never;
-
-export interface CommandTarget {
-  host: string;
-}
-
-export interface CommandClient<C> {
-  issue<N extends keyof C & string>(
-    name: N,
-    input: CommandInput<RecordValue<C, N>>,
-    target: CommandTarget,
-  ): Promise<HostCommandRun<CommandOutput<RecordValue<C, N>>>>;
-  status(id: string): Promise<HostCommandRun | undefined>;
-}
-
-export type ProbeResult =
-  | { status: "ready" }
-  | { status: "degraded"; reasons: Array<{ code: string; message: string }> };
-
-export type Capability = "spawn" | "execute-commands" | "land" | (string & {});
-
-export interface HealthReporter {
-  report(probe: string, result: ProbeResult): void;
-  capability(capability: Capability, host?: string): Promise<boolean>;
-}
-
-type SecretName<S> = S extends readonly (infer Name extends string)[] ? Name : never;
-
-export interface SecretsReader<S> {
-  get(name: SecretName<S>): Promise<string>;
-}
-
-/**
- * An OPAQUE per-{@link ModuleHost} identity. It carries no capability and no data — a module can only
- * compare it or use it as a `WeakMap` key, to bind module-private state to the exact host instance that
- * is executing (#1506: the inbox binds its admission capability to the host whose gateway claimed it, so
- * a token minted against any other object is inert here). A look-alike literal is a DIFFERENT object and
- * therefore a different key, which is the whole point: identity is by reference, never by shape.
- */
-export interface HostIdentity {
-  readonly hostIdentity: true;
-}
-
-export interface ModuleCtx<M extends AnyManifest = AnyManifest> {
-  /** The opaque identity of the host executing this op — see {@link HostIdentity}. */
-  readonly hostIdentity: HostIdentity;
-  readonly principal: Principal;
-  readonly trace: TraceContext;
-  readonly config: ResolvedConfig<M["config"]>;
-  readonly entities: EntityStores<M["entities"]>;
-  readonly events: EventWriter<NonNullable<M["events"]>>;
-  readonly workflows: WorkflowClient<NonNullable<M["workflows"]>>;
-  readonly commands: CommandClient<NonNullable<M["commands"]>>;
-  /** Dormant Stage-0 bridge for MESSAGE timer authority mutations. The participant is scoped to
-   *  this op/step attempt and commits only with its entity/event/journal transaction. */
-  readonly messageAuthority: MessageAuthorityParticipant;
-  readonly health: HealthReporter;
-  readonly secrets: SecretsReader<NonNullable<M["secrets"]>>;
-  readonly clock: Clock;
-  readonly rng: Rng;
-  readonly net: Transport;
-  readonly log: Logger;
-}
-
-export interface OpExposure {
-  http?: boolean;
-  mcp?: boolean;
-  cli?: boolean;
-}
-
-export interface OpDecl<In extends Schema = z.ZodType<any>, Out extends Schema = z.ZodType<any>> {
-  kind: "query" | "mutation";
-  input: In;
-  output: Out;
-  grant: Grant;
-  /**
-   * The scope requirement a transport ADVERTISES for this op (MCP `tools/list.requiredScopes`, the
-   * OpenAPI security surface). Defaults to `[grant]`. Set this ONLY when the handler enforces a
-   * STRICTER requirement than the entry `grant` — e.g. an op that declares `control:read` to gate
-   * entry but is admin-only in-handler because it reads an owner-less table. Advertising `[grant]`
-   * there would name a scope that ALWAYS 403s; advertising the real requirement keeps the published
-   * surface honest. Purely advisory: the invoker still gates on `grant`, so this changes no
-   * authorization decision — it only fixes what the derived tool/OpenAPI surface CLAIMS is required.
-   */
-  advertiseScopes?: readonly Grant[];
-  summary: string;
-  emits?: readonly EventName[];
-  idempotent?: boolean;
-  expose?: OpExposure;
-  http?: { method: HttpMethod; path: string };
-  handler(ctx: ModuleCtx, input: z.input<In>): Promise<z.output<Out>>;
-}
-
-export class OpError extends Error {
-  constructor(
-    readonly code: string,
-    readonly status: number,
-    message: string,
-    readonly fields?: Readonly<Record<string, readonly string[]>>,
-  ) {
-    super(message);
-    this.name = "OpError";
-  }
-}
-
-export type RetryBackoff =
-  | { kind: "fixed"; delayMs: number }
-  | { kind: "exponential"; initialMs: number; maxMs: number; multiplier?: number };
-
-export interface RetryPolicy {
-  maxAttempts: number;
-  backoff: RetryBackoff;
-  jitter?: number;
-}
-
-export type WaitCondition =
-  | { kind: "event"; topic: EventName; correlationId?: string }
-  | { kind: "command"; commandId: string };
-
-export interface WorkflowDecl<In = any, State extends JsonValue = any> {
-  input: z.ZodType<In>;
-  state: z.ZodType<State>;
-  init(input: In): State;
-  start: StepName;
-  steps: Record<StepName, StepDecl<State>>;
-}
-
-export interface StepDecl<State extends JsonValue> {
-  run(ctx: ModuleCtx, state: State): Promise<StepResult<State>>;
-  retry?: RetryPolicy;
-  timeoutMs?: number;
-}
-
-export type StepResult<State extends JsonValue> =
-  | { state: State; next: StepName }
-  | { state: State; next: "done"; output?: unknown }
-  | { state: State; next: StepName; sleepUntil: number }
-  | { state: State; next: StepName; waitFor: WaitCondition };
-
-export interface HostCommandDecl<In = any, Out = any> {
-  input: z.ZodType<In>;
-  result: z.ZodType<Out>;
-  target: "host-agent" | "runner";
-  grant: Grant;
-  idempotencyKey(input: In): string;
-  timeoutMs: number;
-  retry?: RetryPolicy;
-  whenDegraded?: "queue" | "reject";
-}
-
-export interface ProbeDecl {
-  intervalMs?: number;
-  check?(ctx: ModuleCtx): Promise<ProbeResult>;
-  degrades: Capability[];
-}
-
-export interface HealthDecl {
-  probes: Record<string, ProbeDecl>;
-}
-
-export interface EventTopicSelector {
-  topics: readonly EventName[];
-  cursor?: string;
-}
-
-export interface WsHandlerSlot {
-  onMessage(data: string | Uint8Array): void | Promise<void>;
-  onClose?(code: number, reason: string): void | Promise<void>;
-  onError?(error: unknown): void | Promise<void>;
-}
-
-export type RawRouteDecl =
-  | {
-      method: HttpMethod;
-      path: string;
-      grant: Grant;
-      handler(ctx: ModuleCtx, req: Request): Promise<Response>;
-    }
-  | {
-      streaming: "sse";
-      path: string;
-      grant: Grant;
-      subscribe(ctx: ModuleCtx, req: Request): EventTopicSelector;
-    }
-  | {
-      streaming: "websocket";
-      path: string;
-      grant: Grant;
-      accept(ctx: ModuleCtx, req: Request): WsHandlerSlot;
-    };
-
-export type CellRenderer = unknown;
-
-export type UiSurface =
-  | { kind: "table"; entity: string; columns?: string[]; rowActions?: string[]; customCells?: Record<string, CellRenderer> }
-  | { kind: "detail"; entity: string; customCells?: Record<string, CellRenderer> }
-  | { kind: "form"; op: string }
-  | { kind: "settings" }
-  | { kind: "runs"; entity: string; statusField: string }
-  | { kind: "healthMatrix" };
-
-export interface UiDecl {
-  nav?: { section: string; icon: string; order?: number };
-  surfaces?: UiSurface[];
-  custom?: () => Promise<{ default: unknown }>;
-}
-
-export interface AgentContextDecl {
-  summary: string;
-  examples?: Array<{ intent: string; call: string }>;
-  caveats?: string[];
-}
-
-export interface MigrationHandle {
-  select<T extends JsonValue = JsonValue>(sql: string, params?: readonly JsonValue[]): Promise<readonly T[]>;
-  execute(sql: string, params?: readonly JsonValue[]): Promise<{ changes: number }>;
-}
-
-export interface DataMigration {
-  id: string;
-  run(handle: MigrationHandle): Promise<void>;
-}
-
-export interface ModuleManifest {
-  id: string;
-  title: string;
-  description: string;
-  config?: ConfigDecl;
-  entities?: Record<string, EntityDecl>;
-  events?: Record<EventName, Schema>;
-  ops?: Record<string, OpDecl<any, any>>;
-  routes?: readonly RawRouteDecl[];
-  workflows?: Record<string, WorkflowDecl<any, any>>;
-  commands?: Record<string, HostCommandDecl<any, any>>;
-  health?: HealthDecl;
-  secrets?: readonly string[];
-  ui?: UiDecl;
-  agentContext?: AgentContextDecl;
-  data?: readonly DataMigration[];
-}
-
-export type AnyManifest = ModuleManifest;
-
-type InvalidEventNames<M extends ModuleManifest> = M["events"] extends Record<string, unknown>
-  ? Exclude<keyof M["events"], `${M["id"]}.${string}`>
-  : never;
-
-type InvalidEmittedNames<M extends ModuleManifest> = M["ops"] extends Record<string, OpDecl<any, any>>
-  ? {
-      // An op that omits the optional `emits` has nothing to check; only a concretely declared
-      // list (no `undefined` in its type) is verified against the manifest's events. Without this
-      // guard, an absent `emits` widens to `EventName[]` and every emit-less op false-positives.
-      [K in keyof M["ops"]]: undefined extends M["ops"][K]["emits"]
-        ? never
-        : Exclude<NonNullable<M["ops"][K]["emits"]>[number], keyof NonNullable<M["events"]>>;
-    }[keyof M["ops"]]
-  : never;
-
-type InvalidWorkflowState<M extends ModuleManifest> = M["workflows"] extends Record<string, WorkflowDecl<any, any>>
-  ? {
-      [K in keyof M["workflows"]]: SchemaOutput<M["workflows"][K]["state"]> extends JsonValue ? never : K;
-    }[keyof M["workflows"]]
-  : never;
-
-type LowerAlpha = "a" | "b" | "c" | "d" | "e" | "f" | "g" | "h" | "i" | "j" | "k" | "l" | "m"
-  | "n" | "o" | "p" | "q" | "r" | "s" | "t" | "u" | "v" | "w" | "x" | "y" | "z";
-type Digit = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9";
-
-type IsKebabSegment<S extends string> = S extends `${infer First}${infer Rest}`
-  ? First extends LowerAlpha
-    ? Rest extends ""
-      ? true
-      : Rest extends `${LowerAlpha | Digit}${infer Tail}`
-        ? IsKebabRemainder<Tail>
-        : false
-    : false
-  : false;
-
-type IsKebabRemainder<S extends string> = S extends ""
-  ? true
-  : S extends `${LowerAlpha | Digit}${infer Rest}`
-    ? IsKebabRemainder<Rest>
-    : false;
-
-type IsKebabId<S extends string> = S extends `${infer Head}-${infer Tail}`
-  ? IsKebabSegment<Head> extends true
-    ? IsKebabId<Tail>
-    : false
-  : IsKebabSegment<S>;
-
-type InvalidModuleId<M extends ModuleManifest> = string extends M["id"]
-  ? never
-  : IsKebabId<M["id"]> extends true ? never : M["id"];
-
-type ReservedModuleId<M extends ModuleManifest> = string extends M["id"]
-  ? never
-  : Extract<M["id"], "command">;
-
-type InvalidEntityFields<M extends ModuleManifest> = M["entities"] extends Record<string, EntityDecl>
-  ? {
-      [K in keyof M["entities"]]: Extract<
-        keyof SchemaOutput<M["entities"][K]["schema"]>,
-        "scope" | "version" | "created_at" | "updated_at"
-      >;
-    }[keyof M["entities"]]
-  : never;
-
-type InvalidWorkflowStart<M extends ModuleManifest> = M["workflows"] extends Record<string, WorkflowDecl<any, any>>
-  ? {
-      [K in keyof M["workflows"]]: Exclude<M["workflows"][K]["start"], keyof M["workflows"][K]["steps"]>;
-    }[keyof M["workflows"]]
-  : never;
-
-type MissingMutationIdempotency<M extends ModuleManifest> = M["ops"] extends Record<string, OpDecl<any, any>>
-  ? {
-      [K in keyof M["ops"]]: M["ops"][K] extends { kind: "mutation" }
-        ? M["ops"][K] extends { idempotent: boolean } ? never : K
-        : never;
-    }[keyof M["ops"]]
-  : never;
-
-type ValidationFailure<Message extends string, Detail> = {
-  readonly __manifestError__: Message;
-  readonly __manifestErrorDetail__: Detail;
-};
-
-/** Compile-time cross-field checks that the individual declaration types cannot express. */
-export type ValidateManifest<M extends ModuleManifest> = M
-  & ([InvalidModuleId<M>] extends [never]
-    ? unknown
-    : ValidationFailure<"module id must be kebab-case", InvalidModuleId<M>>)
-  & ([ReservedModuleId<M>] extends [never]
-    ? unknown
-    : ValidationFailure<"module id is reserved", ReservedModuleId<M>>)
-  & ([InvalidEventNames<M>] extends [never]
-    ? unknown
-    : ValidationFailure<"event names must begin with '<module-id>.'", InvalidEventNames<M>>)
-  & ([InvalidEmittedNames<M>] extends [never]
-    ? unknown
-    : ValidationFailure<"ops may only emit events declared by this module", InvalidEmittedNames<M>>)
-  & ([InvalidWorkflowState<M>] extends [never]
-    ? unknown
-    : ValidationFailure<"workflow state must be JSON-safe", InvalidWorkflowState<M>>)
-  & ([InvalidEntityFields<M>] extends [never]
-    ? unknown
-    : ValidationFailure<"entity schemas may not declare kernel-owned fields", InvalidEntityFields<M>>)
-  & ([InvalidWorkflowStart<M>] extends [never]
-    ? unknown
-    : ValidationFailure<"workflow start must name a declared step", InvalidWorkflowStart<M>>)
-  & ([MissingMutationIdempotency<M>] extends [never]
-    ? unknown
-    : ValidationFailure<"mutations must declare idempotent", MissingMutationIdempotency<M>>);
-
-/** A validated manifest, preserving all literal and schema inference from its declaration. */
-export type ModuleDefinition<M extends ModuleManifest = ModuleManifest> = Readonly<M> & {
-  readonly [ModuleDefinitionBrand]: true;
-};
-
-/** Validate once at the declaration boundary; no module runtime is started here. */
-export function defineModule<const M extends ModuleManifest>(manifest: ValidateManifest<M>): ModuleDefinition<M> {
-  assertValidManifest(manifest);
-  return manifest as unknown as ModuleDefinition<M>;
-}