@smthrs/gateway 0.35.0 → 1.0.0-rc.3

package/src/internal/nativeResolution.ts

@@ -0,0 +1,103 @@
+/**
+ * Committed native results and the control binding that authorizes them.
+ * @since 1.0.0
+ */
+
+import type { ControlSchema } from "@smthrs/control"
+
+interface Identity {
+  readonly runId: string
+  readonly executionId: string
+}
+
+/**
+ * Kept across bounded journal windows; only the host's root binding authorizes output.
+ * @category models
+ * @since 1.0.0
+ */
+export interface NativeResolution {
+  readonly binding?: Identity | undefined
+  readonly result?: (Identity & { readonly text: string }) | undefined
+  readonly conflict?: true | undefined
+}
+
+const record = (value: unknown): Record<string, unknown> =>
+  value !== null && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : {}
+const same = (left: Identity, right: Identity): boolean =>
+  left.runId === right.runId && left.executionId === right.executionId
+const position = (value: unknown): boolean => typeof value === "number" && Number.isSafeInteger(value) && value >= 0
+
+/**
+ * A root's committed success is authoritative; child outputs and telemetry are not.
+ * @category projections
+ * @since 1.0.0
+ */
+export const fromEvent = (event: ControlSchema.ControlEvent): NativeResolution | undefined => {
+  if (event.runId === undefined || event.runId.length === 0) return undefined
+  const bridge = record(event.payload)
+  if (event.kind === "control.engine.bound") {
+    return bridge.version === 1 && bridge.controlRunId === event.runId &&
+        typeof bridge.executionId === "string" && bridge.executionId.length > 0
+      ? { binding: { runId: event.runId, executionId: bridge.executionId } }
+      : { conflict: true }
+  }
+  if (
+    event.kind !== "control.engine.event" || bridge.version !== 1 ||
+    typeof bridge.executionId !== "string" || !position(bridge.generation) || !position(bridge.sequence) ||
+    bridge.eventType !== "flows.engine.run-decision"
+  ) return undefined
+  const decision = record(bridge.payload)
+  const fact = record(decision.executionFact)
+  const observation = record(fact.observation)
+  const state = record(decision.state)
+  const input = record(state.payload)
+  const result = record(state.result)
+  const exit = record(result.exit)
+  if (
+    decision.decision !== "transitioned" || decision.status !== "completed" || fact.version !== 1 ||
+    (fact.baseline !== "created" && fact.baseline !== "legacy") ||
+    observation.executionId !== bridge.executionId || observation.status !== "completed" ||
+    observation.flowName !== "agent/run" || state.version !== 1 || state.flowName !== "agent/run" ||
+    input.runId !== event.runId || typeof input.planId !== "string" || input.planId.length === 0 ||
+    result._tag !== "Complete" || exit._tag !== "Success" || !Object.hasOwn(exit, "value")
+  ) return undefined
+  try {
+    const text = typeof exit.value === "string" ? exit.value : JSON.stringify(exit.value)
+    return text === undefined ? undefined : { result: { runId: event.runId, executionId: bridge.executionId, text } }
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * Combining adjacent windows retains the binding even after its event is evicted.
+ * @category projections
+ * @since 1.0.0
+ */
+export const combine = (
+  earlier: NativeResolution | undefined,
+  later: NativeResolution | undefined
+): NativeResolution | undefined => {
+  if (earlier === undefined) return later
+  if (later === undefined) return earlier
+  const conflict = earlier.conflict || later.conflict ||
+    (earlier.binding !== undefined && later.binding !== undefined && !same(earlier.binding, later.binding)) ||
+    (earlier.result !== undefined && later.result !== undefined &&
+      (!same(earlier.result, later.result) || earlier.result.text !== later.result.text))
+  return {
+    binding: later.binding ?? earlier.binding,
+    result: later.result ?? earlier.result,
+    ...(conflict ? { conflict: true } : {})
+  }
+}
+
+/**
+ * Returns output only for one unambiguous, bound root.
+ * @category projections
+ * @since 1.0.0
+ */
+export const output = (value: NativeResolution | undefined): string | undefined =>
+  value?.conflict !== true && value?.binding !== undefined && value.result !== undefined &&
+    same(value.binding, value.result) ?
+    value.result.text :
+    undefined

package/src/internal/nodeEvents.ts

@@ -0,0 +1,100 @@
+/**
+ * Shared engine node-record identity rules for the duration projection.
+ *
+ * A host copies every engine journal entry of a run into the control journal
+ * as a `control.engine.event` envelope, so the node records both executors
+ * write arrive here verbatim. The envelope's own fields are guarded the way
+ * `callEvents.ts` guards them, and the record inside it is decoded with the
+ * payload schemas `@smthrs/journal` publishes rather than with a second,
+ * hand-written copy of the same contract.
+ *
+ * @since 1.0.0
+ */
+
+import { EngineEvent } from "@smthrs/journal"
+import type * as Option from "effect/Option"
+import * as Schema from "effect/Schema"
+
+/** A sparse historical observation is readable without inventing missing fields.
+ * @category models
+ * @since 1.0.0
+ */
+export interface NodeObservation {
+  readonly kind?: string | undefined
+  readonly payload?: unknown
+}
+
+/**
+ * One node record, with the envelope coordinates that scope and stamp it.
+ *
+ * `executionId` is the native run the record belongs to, which is what keeps
+ * two executions of one node id apart, and `emittedAtMs` is the native
+ * timestamp the engine wrote, which is what a duration is measured between.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export interface NodeRecord<Payload> {
+  readonly executionId: string
+  readonly emittedAtMs: number
+  readonly payload: Payload
+}
+
+/**
+ * The envelope of a versioned native record, or nothing.
+ *
+ * Only `version`, `executionId` and `emittedAtMs` are guarded, because those
+ * are the fields a duration fold reads. The native `generation` and `sequence`
+ * are not: the fold pairs a settlement with the last schedule of the same
+ * execution and node, in the order the control journal committed them, so
+ * neither one changes what it computes.
+ */
+const envelopeOf = (event: NodeObservation): Record<string, unknown> | undefined => {
+  if (event.kind !== "control.engine.event" || typeof event.payload !== "object" || event.payload === null) {
+    return undefined
+  }
+  const envelope = event.payload as Record<string, unknown>
+  if (
+    envelope.version !== 1 || typeof envelope.executionId !== "string" ||
+    typeof envelope.emittedAtMs !== "number" || !Number.isFinite(envelope.emittedAtMs)
+  ) return undefined
+  return envelope
+}
+
+/** One record of the named type, decoded by the journal's own payload schema. */
+const nodeRecord = <A>(
+  event: NodeObservation,
+  eventType: string,
+  decode: (payload: unknown) => Option.Option<A>
+): NodeRecord<A> | undefined => {
+  const envelope = envelopeOf(event)
+  if (envelope === undefined || envelope.eventType !== eventType) return undefined
+  const payload = decode(envelope.payload)
+  if (payload._tag === "None") return undefined
+  return {
+    executionId: envelope.executionId as string,
+    emittedAtMs: envelope.emittedAtMs as number,
+    payload: payload.value
+  }
+}
+
+const decodeScheduled = Schema.decodeUnknownOption(EngineEvent.NodeScheduledPayload)
+const decodeSettled = Schema.decodeUnknownOption(EngineEvent.NodeSettledPayload)
+
+/** A node the executor admitted, as the engine recorded it.
+ * @category projections
+ * @since 1.0.0
+ */
+export const nodeScheduled = (
+  event: NodeObservation
+): NodeRecord<EngineEvent.NodeScheduledPayload> | undefined =>
+  nodeRecord(event, EngineEvent.nodeEventTypes.nodeScheduled, decodeScheduled)
+
+/** A node that reached an outcome, as the engine recorded it.
+ * @category projections
+ * @since 1.0.0
+ */
+export const nodeSettled = (
+  event: NodeObservation
+): NodeRecord<EngineEvent.NodeSettledPayload> | undefined =>
+  nodeRecord(event, EngineEvent.nodeEventTypes.nodeSettled, decodeSettled)

package/src/node/NodeGateway.ts

@@ -0,0 +1,30 @@
+/** Node HTTP adapter for the shared native gateway policy and protocol.
+ * @since 1.0.0
+ */
+
+import * as NodeHttpServer from "@effect/platform-node/NodeHttpServer"
+import { createServer } from "node:http"
+import * as NativeGateway from "../internal/NativeGateway.ts"
+
+export {
+  bearerPrincipal,
+  bindRefusal,
+  defaultServerOptions,
+  ingressOptions,
+  isLoopbackHost,
+  layerAuth,
+  listenOptions,
+  scopedPrincipal,
+  scopedTokenPaths
+} from "../internal/NativeGateway.ts"
+/** Node socket and shared gateway policy options.
+ * @since 1.0.0
+ * @category models
+ */
+export type ServerOptions = NativeGateway.ServerOptions
+
+/** Hosts the existing workspace gateway on Node's scoped HTTP server.
+ * @since 1.0.0
+ * @category layers
+ */
+export const layer = NativeGateway.makeLayer((options) => NodeHttpServer.layer(createServer, options))