@beignet/core 0.0.2 → 0.0.4

package/src/ports/unbound.ts

@@ -0,0 +1,64 @@
+/**
+ * Unbound port placeholders for deferred `definePorts(...)` keys.
+ *
+ * Ports declared as deferred boot as marked placeholders. Any method call on
+ * a placeholder throws a descriptive error, and `createServer(...)` scans
+ * final ports after provider startup so a missing provider fails boot instead
+ * of failing on first use.
+ */
+
+const UNBOUND_PORT_MARKER = Symbol.for("beignet.unboundPort");
+
+function unboundPortMessage(portName: string): string {
+  return (
+    `Port "${portName}" is not bound. "${portName}" is declared as deferred ` +
+    "in definePorts(...). Register a provider that contributes it " +
+    "(server/providers.ts) or bind it in infra/app-ports.ts."
+  );
+}
+
+/**
+ * Create a marked placeholder for a deferred port.
+ *
+ * Property access returns a function that throws, so calling any method on an
+ * unbound port produces a descriptive error naming the port.
+ */
+export function createUnboundPort(portName: string): unknown {
+  return new Proxy(
+    {},
+    {
+      get(_target, property) {
+        if (property === UNBOUND_PORT_MARKER) return true;
+        if (property === Symbol.toStringTag) {
+          return `UnboundPort(${portName})`;
+        }
+        // Keep unbound ports safe to `await` and JSON-serialize.
+        if (property === "then" || property === "toJSON") return undefined;
+        if (typeof property === "symbol") return undefined;
+        if (property === "toString") {
+          return () => `[unbound port "${portName}"]`;
+        }
+
+        return () => {
+          throw new Error(unboundPortMessage(portName));
+        };
+      },
+    },
+  );
+}
+
+/**
+ * Check whether a value is an unbound port placeholder created for a deferred
+ * `definePorts(...)` key.
+ */
+export function isUnboundPort(value: unknown): boolean {
+  if (value === null || typeof value !== "object") return false;
+
+  try {
+    return (
+      (value as Record<PropertyKey, unknown>)[UNBOUND_PORT_MARKER] === true
+    );
+  } catch {
+    return false;
+  }
+}

package/src/ports/unit-of-work.ts

@@ -1,5 +1,9 @@
-import { parseEventPayload } from "../events";
-import type { DomainEventDef, EventBusPort, InferEventPayload } from "./events";
+import { parseEventPayload } from "../events/index.js";
+import type {
+  DomainEventDef,
+  EventBusPort,
+  InferEventPayload,
+} from "./events.js";
 
 type MaybePromise<T> = T | Promise<T>;
 

package/src/providers/index.ts

@@ -13,6 +13,7 @@ export {
   isProviderInstrumentation,
   isProviderInstrumentationPort,
   type JobProviderInstrumentationEvent,
+  type OutboxProviderInstrumentationEvent,
   type ProviderCustomInstrumentationEventInput,
   type ProviderInstrumentation,
   type ProviderInstrumentationEvent,
@@ -26,15 +27,27 @@ export {
   resolveProviderInstrumentationPort,
   type ScheduleProviderInstrumentationEvent,
   type UseCaseProviderInstrumentationEvent,
-} from "./instrumentation";
+} from "./instrumentation.js";
 export {
+  type ProviderPackageMetadata,
+  type ProviderPackageMetadataIssue,
+  type ProviderPackageMetadataParseResult,
+  type ProviderPackagePortMetadata,
+  type ProviderPackageRegistrationMetadata,
+  type ProviderPackageRegistrationSeverity,
+  parseProviderPackageMetadata,
+} from "./metadata.js";
+export {
+  type AnyServiceProvider,
   createProvider,
   type InferOutput,
+  type InferProviderPorts,
   type MaybePromise,
   type ProvidedPortsOf,
-  type ProvidedPortsOfList,
   type ProviderConfigDef,
   type ProviderLifecycleContext,
+  type ProviderServiceContextFactory,
   type ProviderSetupResult,
   type ServiceProvider,
-} from "./provider";
+  type ServiceProviderMetadata,
+} from "./provider.js";

package/src/providers/instrumentation.ts

@@ -1,4 +1,4 @@
-import { type Redactor, redactValue } from "../ports/redaction";
+import { type Redactor, redactValue } from "../ports/redaction.js";
 
 /**
  * Logical provider watcher name used to toggle groups of instrumentation
@@ -68,6 +68,10 @@ export interface RequestProviderInstrumentationEvent
    * Matched contract name, when known.
    */
   contractName?: string;
+  /**
+   * Which layer produced the response.
+   */
+  responseOwner?: "route" | "framework" | "transport" | "unknown";
   /**
    * Response status code.
    */
@@ -104,6 +108,19 @@ export interface ErrorProviderInstrumentationEvent
    * Use case associated with the error.
    */
   useCaseName?: string;
+  /**
+   * Which layer owns the error.
+   */
+  owner?:
+    | "route"
+    | "framework"
+    | "provider"
+    | "job"
+    | "schedule"
+    | "outbox"
+    | "client"
+    | "devtools"
+    | "unknown";
 }
 
 /**
@@ -159,11 +176,41 @@ export interface JobProviderInstrumentationEvent
   /**
    * Job lifecycle status.
    */
-  status: "scheduled" | "started" | "completed" | "failed";
+  status:
+    | "scheduled"
+    | "started"
+    | "completed"
+    | "failed"
+    | "retryScheduled"
+    | "deadLettered";
+}
+
+/**
+ * Durable outbox delivery instrumentation.
+ */
+export interface OutboxProviderInstrumentationEvent
+  extends BaseProviderInstrumentationEvent {
+  type: "outbox";
+  /**
+   * Durable outbox message ID.
+   */
+  messageId: string;
+  /**
+   * Message kind.
+   */
+  messageKind: "event" | "job";
+  /**
+   * Event or job name stored in the outbox message.
+   */
+  messageName: string;
+  /**
+   * Delivery lifecycle status.
+   */
+  status: "delivered" | "retryScheduled" | "deadLettered";
 }
 
 /**
- * Scheduled task instrumentation.
+ * Schedule instrumentation.
  */
 export interface ScheduleProviderInstrumentationEvent
   extends BaseProviderInstrumentationEvent {
@@ -231,6 +278,7 @@ export type ProviderInstrumentationEvent =
   | UseCaseProviderInstrumentationEvent
   | EventBusProviderInstrumentationEvent
   | JobProviderInstrumentationEvent
+  | OutboxProviderInstrumentationEvent
   | ScheduleProviderInstrumentationEvent
   | ProviderLifecycleInstrumentationEvent
   | CustomProviderInstrumentationEvent;
@@ -310,6 +358,10 @@ export interface ProviderInstrumentation {
 
 /**
  * Values accepted by `createProviderInstrumentation(...)`.
+ *
+ * Plain ports objects are accepted so callers can pass `ctx.ports` (or a
+ * provider's `ports` argument) directly; the resolver reads
+ * `ports.instrumentation`, then `ports.devtools`.
  */
 export type ProviderInstrumentationTarget =
   | ProviderInstrumentationPort
@@ -318,6 +370,7 @@ export type ProviderInstrumentationTarget =
       devtools?: ProviderInstrumentationPort | ProviderInstrumentation;
       instrumentation?: ProviderInstrumentationPort | ProviderInstrumentation;
     }
+  | Record<string, unknown>
   | undefined;
 
 function isObject(value: unknown): value is Record<string, unknown> {
@@ -326,12 +379,19 @@ function isObject(value: unknown): value is Record<string, unknown> {
 
 /**
  * Return whether a value is a provider instrumentation helper.
+ *
+ * Checks key presence with `in` before reading so probing proxy-backed
+ * objects, such as test-context port guards that throw on unknown reads,
+ * stays safe.
  */
 export function isProviderInstrumentation(
   value: unknown,
 ): value is ProviderInstrumentation {
   return (
     isObject(value) &&
+    "record" in value &&
+    "custom" in value &&
+    "isEnabled" in value &&
     typeof value.record === "function" &&
     typeof value.custom === "function" &&
     typeof value.isEnabled === "function"
@@ -340,11 +400,16 @@ export function isProviderInstrumentation(
 
 /**
  * Return whether a value is a provider instrumentation port.
+ *
+ * Checks key presence with `in` before reading so probing proxy-backed
+ * objects stays safe.
  */
 export function isProviderInstrumentationPort(
   value: unknown,
 ): value is ProviderInstrumentationPort {
-  return isObject(value) && typeof value.record === "function";
+  return (
+    isObject(value) && "record" in value && typeof value.record === "function"
+  );
 }
 
 function resolveProviderInstrumentationValue(
@@ -370,8 +435,12 @@ export function resolveProviderInstrumentationPort(
   if (!isObject(target)) return undefined;
 
   return (
-    resolveProviderInstrumentationValue(target.instrumentation) ??
-    resolveProviderInstrumentationValue(target.devtools)
+    resolveProviderInstrumentationValue(
+      "instrumentation" in target ? target.instrumentation : undefined,
+    ) ??
+    resolveProviderInstrumentationValue(
+      "devtools" in target ? target.devtools : undefined,
+    )
   );
 }
 
@@ -387,6 +456,18 @@ function withProviderDetails(providerName: string, details: unknown): unknown {
   return { providerName, value: details };
 }
 
+function withInstrumentationProviderDetails(
+  event: ProviderInstrumentationEventInput,
+  providerName: string,
+): ProviderInstrumentationEventInput {
+  if (event.type === "provider") return event;
+
+  return {
+    ...event,
+    details: withProviderDetails(providerName, event.details),
+  } as ProviderInstrumentationEventInput;
+}
+
 /**
  * Create a provider instrumentation helper that handles watcher checks,
  * default watcher assignment, redaction, and sink failures.
@@ -417,12 +498,16 @@ export function createProviderInstrumentation(
       options.watcher && event.watcher === undefined
         ? { ...event, watcher: options.watcher }
         : event;
+    const eventWithProvider = withInstrumentationProviderDetails(
+      eventWithWatcher,
+      options.providerName,
+    );
 
     let redacted: ProviderInstrumentationEventInput;
     try {
       redacted = options.redact
-        ? options.redact(redactValue(eventWithWatcher))
-        : redactValue(eventWithWatcher);
+        ? options.redact(redactValue(eventWithProvider))
+        : redactValue(eventWithProvider);
     } catch {
       return undefined;
     }

package/src/providers/metadata.ts

@@ -0,0 +1,234 @@
+/**
+ * Static provider package metadata declared in package.json under
+ * `beignet.provider`.
+ *
+ * This metadata is for docs and tooling. It must stay side-effect-free and
+ * does not change provider setup, ordering, or runtime port merging behavior.
+ */
+
+export type ProviderPackagePortMetadata = {
+  name: string;
+  type: string;
+};
+
+export type ProviderPackageRegistrationSeverity = "warning" | "hint";
+
+export type ProviderPackageRegistrationMetadata = {
+  required?: boolean;
+  severity?: ProviderPackageRegistrationSeverity;
+  tokens?: readonly string[];
+};
+
+export type ProviderPackageMetadata = {
+  displayName?: string;
+  ports?: readonly string[];
+  appPorts?: readonly ProviderPackagePortMetadata[];
+  env?: readonly string[];
+  requiredEnv?: readonly string[];
+  registration?: ProviderPackageRegistrationMetadata;
+  watchers?: readonly string[];
+};
+
+export type ProviderPackageMetadataIssue = {
+  path: string;
+  message: string;
+};
+
+export type ProviderPackageMetadataParseResult =
+  | { success: true; metadata: ProviderPackageMetadata }
+  | { success: false; issues: readonly ProviderPackageMetadataIssue[] };
+
+export function parseProviderPackageMetadata(
+  input: unknown,
+): ProviderPackageMetadataParseResult {
+  if (!isRecord(input)) {
+    return {
+      success: false,
+      issues: [
+        {
+          path: "beignet.provider",
+          message: "must be an object",
+        },
+      ],
+    };
+  }
+
+  const issues: ProviderPackageMetadataIssue[] = [];
+  const metadata: ProviderPackageMetadata = {};
+
+  if (input.displayName !== undefined) {
+    if (typeof input.displayName !== "string") {
+      issues.push({
+        path: "beignet.provider.displayName",
+        message: "must be a string",
+      });
+    } else {
+      metadata.displayName = input.displayName;
+    }
+  }
+
+  const ports = parseStringArray(input.ports, "beignet.provider.ports", issues);
+  if (ports !== undefined) metadata.ports = ports;
+
+  const env = parseStringArray(input.env, "beignet.provider.env", issues);
+  if (env !== undefined) metadata.env = env;
+
+  const requiredEnv = parseStringArray(
+    input.requiredEnv,
+    "beignet.provider.requiredEnv",
+    issues,
+  );
+  if (requiredEnv !== undefined) {
+    metadata.requiredEnv = requiredEnv;
+    const envSet = new Set(env ?? []);
+    for (const envVar of requiredEnv) {
+      if (!envSet.has(envVar)) {
+        issues.push({
+          path: "beignet.provider.requiredEnv",
+          message: `${envVar} must also be listed in beignet.provider.env`,
+        });
+      }
+    }
+  }
+
+  const watchers = parseStringArray(
+    input.watchers,
+    "beignet.provider.watchers",
+    issues,
+  );
+  if (watchers !== undefined) metadata.watchers = watchers;
+
+  const appPorts = parseAppPorts(input.appPorts, issues);
+  if (appPorts !== undefined) metadata.appPorts = appPorts;
+
+  const registration = parseRegistration(input.registration, issues);
+  if (registration !== undefined) metadata.registration = registration;
+
+  if (issues.length > 0) {
+    return { success: false, issues };
+  }
+
+  return { success: true, metadata };
+}
+
+function parseStringArray(
+  value: unknown,
+  path: string,
+  issues: ProviderPackageMetadataIssue[],
+): string[] | undefined {
+  if (value === undefined) return undefined;
+  if (!Array.isArray(value)) {
+    issues.push({ path, message: "must be an array of strings" });
+    return undefined;
+  }
+
+  const parsed: string[] = [];
+  for (const [index, entry] of value.entries()) {
+    if (typeof entry !== "string") {
+      issues.push({
+        path: `${path}[${index}]`,
+        message: "must be a string",
+      });
+      continue;
+    }
+    parsed.push(entry);
+  }
+
+  return parsed;
+}
+
+function parseAppPorts(
+  value: unknown,
+  issues: ProviderPackageMetadataIssue[],
+): ProviderPackagePortMetadata[] | undefined {
+  if (value === undefined) return undefined;
+  const path = "beignet.provider.appPorts";
+  if (!Array.isArray(value)) {
+    issues.push({ path, message: "must be an array of port metadata objects" });
+    return undefined;
+  }
+
+  const parsed: ProviderPackagePortMetadata[] = [];
+  for (const [index, entry] of value.entries()) {
+    const entryPath = `${path}[${index}]`;
+    if (!isRecord(entry)) {
+      issues.push({ path: entryPath, message: "must be an object" });
+      continue;
+    }
+    if (typeof entry.name !== "string") {
+      issues.push({ path: `${entryPath}.name`, message: "must be a string" });
+    }
+    if (typeof entry.type !== "string") {
+      issues.push({ path: `${entryPath}.type`, message: "must be a string" });
+    }
+    if (typeof entry.name === "string" && typeof entry.type === "string") {
+      parsed.push({ name: entry.name, type: entry.type });
+    }
+  }
+
+  return parsed;
+}
+
+function parseRegistration(
+  value: unknown,
+  issues: ProviderPackageMetadataIssue[],
+): ProviderPackageRegistrationMetadata | undefined {
+  if (value === undefined) return undefined;
+  const path = "beignet.provider.registration";
+  if (!isRecord(value)) {
+    issues.push({ path, message: "must be an object" });
+    return undefined;
+  }
+
+  const registration: ProviderPackageRegistrationMetadata = {};
+  if (value.required !== undefined) {
+    if (typeof value.required !== "boolean") {
+      issues.push({ path: `${path}.required`, message: "must be a boolean" });
+    } else {
+      registration.required = value.required;
+    }
+  }
+
+  if (value.severity !== undefined) {
+    if (value.severity !== "warning" && value.severity !== "hint") {
+      issues.push({
+        path: `${path}.severity`,
+        message: 'must be "warning" or "hint"',
+      });
+    } else {
+      registration.severity = value.severity;
+    }
+  }
+
+  if (registration.required === true && registration.severity === "hint") {
+    issues.push({
+      path: `${path}.severity`,
+      message: 'must not be "hint" when registration is required',
+    });
+  }
+
+  const tokens = parseStringArray(value.tokens, `${path}.tokens`, issues);
+  if (tokens !== undefined) registration.tokens = tokens;
+
+  if ((tokens?.length ?? 0) === 0) {
+    if (registration.required === true) {
+      issues.push({
+        path: `${path}.tokens`,
+        message:
+          "must include at least one token when registration is required",
+      });
+    } else if (registration.severity !== undefined) {
+      issues.push({
+        path: `${path}.tokens`,
+        message:
+          "must include at least one token when registration severity is set",
+      });
+    }
+  }
+
+  return registration;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}