Build Agentic Organization package architecture slice

agentic-organization/apps/workers/README.md

@@ -0,0 +1,65 @@
+# Agentic Organization Workers App
+
+`apps/workers` is the first runtime-host shell for Agentic
+Organization. It is intentionally small and NodeNext-first so the
+process boundary can be tested before NestJS, real NATS clients,
+CockroachDB connection pools, Kubernetes manifests, or process
+supervisors are introduced.
+
+## Responsibility
+
+The app composes existing packages. It does not own business rules.
+
+Current duties:
+
+- parse typed runtime configuration from process environment values that
+  Kubernetes can later provide through ConfigMaps and Secrets;
+- compose the runtime through a single app-level factory so concrete
+  adapters stay outside domain and package code;
+- run the package-level Organization worker cycle;
+- run the NATS JetStream consumer adapter cycle;
+- pass configured NATS batch size, stream name, and durable consumer
+  name into the adapter boundary;
+- emit worker-cycle and NATS-consumer batch telemetry records;
+- return a healthy/degraded runtime result that makes failures visible
+  without starving the other loop.
+
+## Boundary
+
+`apps/workers` may bind adapter packages and process configuration.
+Packages must not import this app.
+
+The app currently receives ports that tests can fake:
+
+- `OrganizationWorkerHost`;
+- `NatsJetStreamEventConsumer`;
+- `WorkerRuntimeTelemetrySink`.
+
+Future concrete process wiring can bind these ports to CockroachDB,
+NATS, OTLP/logging, health checks, readiness checks, and graceful
+shutdown without changing runtime rule evaluation.
+
+## Environment
+
+The worker app owns process configuration. Packages receive typed
+config and ports; they do not read environment variables.
+
+Required runtime values:
+
+- `AGENTIC_ORG_ENV`;
+- `AGENTIC_ORG_ID`;
+- `NATS_STREAM`;
+- `NATS_DURABLE`;
+- `NATS_INBOUND_BATCH_SIZE`.
+
+URLs, credentials, and other sensitive adapter settings belong in later
+adapter config bound by the composition root. They should come from
+Kubernetes Secrets or ExternalSecrets in the full AI cluster, not from
+domain packages.
+
+## Composition Root
+
+`composeWorkerRuntime` is the app-level seam where already-constructed
+ports are connected to the runtime. Today tests provide fake ports. The
+next production slice should construct real CockroachDB, NATS, and
+telemetry adapters here while preserving the same package contracts.

agentic-organization/apps/workers/src/composition.ts

@@ -0,0 +1,28 @@
+import type { NatsJetStreamEventConsumer } from "../../../packages/messaging-nats/src/index.ts";
+import type { OrganizationWorkerHost } from "../../../packages/workers/src/index.ts";
+import {
+  createWorkerRuntime,
+  type WorkerRuntime,
+  type WorkerRuntimeConfig,
+  type WorkerRuntimeTelemetrySink,
+} from "./worker-runtime.ts";
+
+export type WorkerRuntimePorts = {
+  organizationWorkerHost: OrganizationWorkerHost;
+  natsEventConsumer: NatsJetStreamEventConsumer;
+  telemetrySink: WorkerRuntimeTelemetrySink;
+};
+
+export type ComposeWorkerRuntimeInput = {
+  config: WorkerRuntimeConfig;
+  ports: WorkerRuntimePorts;
+};
+
+export function composeWorkerRuntime(input: ComposeWorkerRuntimeInput): WorkerRuntime {
+  return createWorkerRuntime({
+    config: input.config,
+    organizationWorkerHost: input.ports.organizationWorkerHost,
+    natsEventConsumer: input.ports.natsEventConsumer,
+    telemetrySink: input.ports.telemetrySink,
+  });
+}

agentic-organization/apps/workers/src/config.ts

@@ -0,0 +1,71 @@
+import { WorkerRuntimeConfigError, WorkerRuntimeConfigErrorCode, type WorkerRuntimeConfig } from "./worker-runtime.ts";
+
+const decimalIntegerPattern = /^[0-9]+$/;
+
+export const WorkerProcessEnvName = {
+  AgenticOrgEnv: "AGENTIC_ORG_ENV",
+  AgenticOrgId: "AGENTIC_ORG_ID",
+  NatsDurable: "NATS_DURABLE",
+  NatsInboundBatchSize: "NATS_INBOUND_BATCH_SIZE",
+  NatsStream: "NATS_STREAM",
+} as const;
+
+export type WorkerProcessEnvName = (typeof WorkerProcessEnvName)[keyof typeof WorkerProcessEnvName];
+
+export type WorkerProcessEnvironment = Partial<Record<WorkerProcessEnvName, string | undefined>>;
+
+export function parseWorkerRuntimeConfigFromEnv(env: WorkerProcessEnvironment): WorkerRuntimeConfig {
+  return {
+    environment: readRequiredEnvValue(
+      env,
+      WorkerProcessEnvName.AgenticOrgEnv,
+      WorkerRuntimeConfigErrorCode.MissingEnvironment,
+    ),
+    organizationId: readRequiredEnvValue(
+      env,
+      WorkerProcessEnvName.AgenticOrgId,
+      WorkerRuntimeConfigErrorCode.MissingOrganizationId,
+    ),
+    natsStreamName: readRequiredEnvValue(
+      env,
+      WorkerProcessEnvName.NatsStream,
+      WorkerRuntimeConfigErrorCode.MissingNatsStreamName,
+    ),
+    natsDurableName: readRequiredEnvValue(
+      env,
+      WorkerProcessEnvName.NatsDurable,
+      WorkerRuntimeConfigErrorCode.MissingNatsDurableName,
+    ),
+    natsInboundBatchSize: parseNatsInboundBatchSize(env[WorkerProcessEnvName.NatsInboundBatchSize]),
+  };
+}
+
+function readRequiredEnvValue(
+  env: WorkerProcessEnvironment,
+  name: WorkerProcessEnvName,
+  errorCode: WorkerRuntimeConfigErrorCode,
+): string {
+  const value = env[name];
+
+  if (value === undefined || value.trim().length === 0) {
+    throw new WorkerRuntimeConfigError(errorCode);
+  }
+
+  return value.trim();
+}
+
+function parseNatsInboundBatchSize(value: string | undefined): number {
+  const trimmedValue = value?.trim();
+
+  if (trimmedValue === undefined || trimmedValue.length === 0 || !decimalIntegerPattern.test(trimmedValue)) {
+    throw new WorkerRuntimeConfigError(WorkerRuntimeConfigErrorCode.InvalidNatsInboundBatchSize);
+  }
+
+  const parsedValue = Number(trimmedValue);
+
+  if (!Number.isSafeInteger(parsedValue) || parsedValue < 1) {
+    throw new WorkerRuntimeConfigError(WorkerRuntimeConfigErrorCode.InvalidNatsInboundBatchSize);
+  }
+
+  return parsedValue;
+}

agentic-organization/apps/workers/src/index.ts

@@ -0,0 +1,18 @@
+export { WorkerProcessEnvName, parseWorkerRuntimeConfigFromEnv, type WorkerProcessEnvironment } from "./config.ts";
+export { composeWorkerRuntime, type ComposeWorkerRuntimeInput, type WorkerRuntimePorts } from "./composition.ts";
+export {
+  WorkerRuntimeConfigError,
+  WorkerRuntimeConfigErrorCode,
+  WorkerRuntimeFailureStage,
+  WorkerRuntimeStatus,
+  WorkerRuntimeTelemetryEventName,
+  createWorkerRuntime,
+  type CreateWorkerRuntimeInput,
+  type WorkerRuntime,
+  type WorkerRuntimeConfig,
+  type WorkerRuntimeFailure,
+  type WorkerRuntimeRunResult,
+  type WorkerRuntimeTelemetryAttributes,
+  type WorkerRuntimeTelemetryRecord,
+  type WorkerRuntimeTelemetrySink,
+} from "./worker-runtime.ts";