refactor(javascript): group domain semantics and contracts (#907)

src/domain/javascript/javascriptRuntimeObservation.ts

@@ -0,0 +1,157 @@
+import { z } from "zod";
+
+import { browserEndpointSchema } from "../browserObservation.js";
+import { prefixedDigestSchema } from "../digests.js";
+
+const observationTextSchema = z.string().min(1);
+
+const runtimeEndpoint = {
+  inspector_endpoint: browserEndpointSchema,
+};
+
+/** Input for listing targets exposed by an explicit Node/Electron Inspector endpoint. */
+export const listJavaScriptRuntimeTargetsInputSchema = z.strictObject({
+  ...runtimeEndpoint,
+});
+export type ListJavaScriptRuntimeTargetsInput = z.infer<
+  typeof listJavaScriptRuntimeTargetsInputSchema
+>;
+
+export const javascriptRuntimeKindSchema = z.enum([
+  "node",
+  "electron-main",
+  "electron-preload",
+  "electron-renderer",
+]);
+const observedJavaScriptRuntimeKindSchema = javascriptRuntimeKindSchema.or(
+  z.literal("unknown"),
+);
+
+/** Input for one bounded, attach-only V8 Inspector observation. */
+/** Input for one passive attach-only V8 Inspector observation. */
+export const observeJavaScriptRuntimeInputSchema = z.strictObject({
+  ...runtimeEndpoint,
+  target_id: z.string().trim().min(1),
+  runtime_kind: javascriptRuntimeKindSchema.optional(),
+  observation_ms: z.number().int().min(0).default(100),
+});
+export type ObserveJavaScriptRuntimeInput = z.infer<
+  typeof observeJavaScriptRuntimeInputSchema
+>;
+
+export const javascriptRuntimeVersionSchema = z.strictObject({
+  product: z.string().min(1),
+  protocol_version: z.string().min(1),
+  v8_version: z.string().nullable(),
+});
+
+export const javascriptRuntimeLocationSchema = z.discriminatedUnion("kind", [
+  z.strictObject({
+    kind: z.literal("file"),
+    file_path: z.string().min(1),
+    authority: z.literal("scope-fallback").optional(),
+  }),
+  z.strictObject({
+    kind: z.literal("url"),
+    origin: z.string().min(1),
+    sanitized_url: z.string().min(1),
+  }),
+  z.strictObject({
+    kind: z.literal("builtin"),
+    specifier: z.string().min(1),
+  }),
+]);
+export type JavaScriptRuntimeLocation = z.infer<
+  typeof javascriptRuntimeLocationSchema
+>;
+
+/** Discovery metadata can identify an endpoint target without verifying its file location. */
+export const javascriptRuntimeUnresolvedLocationSchema = z.strictObject({
+  kind: z.literal("unresolved"),
+  reported_url: z.string().min(1),
+  reason: z.literal("unverifiable-file-location"),
+});
+
+/** Verified locations and explicitly unresolved discovery metadata. */
+export const javascriptRuntimeTargetLocationSchema = z.union([
+  javascriptRuntimeLocationSchema,
+  javascriptRuntimeUnresolvedLocationSchema,
+]);
+export type JavaScriptRuntimeTargetLocation = z.infer<
+  typeof javascriptRuntimeTargetLocationSchema
+>;
+
+const javascriptRuntimeTargetSchema = z.strictObject({
+  target_id: z.string().min(1),
+  protocol_type: z.string().min(1),
+  attached: z.boolean(),
+  location: javascriptRuntimeTargetLocationSchema,
+});
+
+/** Complete V8 Inspector target inventory exposed by the selected endpoint. */
+export const javascriptRuntimeTargetListSchema = z.strictObject({
+  runtime: javascriptRuntimeVersionSchema,
+  targets: z.array(javascriptRuntimeTargetSchema),
+  excluded: z.strictObject({
+    unsupported_location: z.number().int().min(0),
+    unconnectable: z.number().int().min(0),
+  }),
+  limitations: z.array(observationTextSchema),
+});
+export type JavaScriptRuntimeTargetList = z.infer<
+  typeof javascriptRuntimeTargetListSchema
+>;
+
+const javascriptRuntimeScriptSchema = z.strictObject({
+  script_key: prefixedDigestSchema("v8_script"),
+  location: javascriptRuntimeLocationSchema,
+  execution_context_key: z.string().nullable(),
+  cdp_hash: z.string().nullable(),
+  length: z.number().int().min(0),
+  is_module: z.boolean(),
+  status: z.literal("observed-loaded"),
+});
+
+const javascriptRuntimeContextSchema = z.strictObject({
+  context_key: z.string().min(1),
+  state: z.enum(["created", "destroyed", "cleared"]),
+  name: z.string().nullable(),
+  origin: z.string().nullable(),
+});
+
+/** Deterministic passive script/context snapshot from one bounded window. */
+export const javascriptRuntimeObservationSchema = z.strictObject({
+  runtime: javascriptRuntimeVersionSchema,
+  target: javascriptRuntimeTargetSchema.extend({
+    runtime_kind: observedJavaScriptRuntimeKindSchema,
+    runtime_kind_authority: z.enum([
+      "caller-declared-unverified",
+      "not-declared",
+    ]),
+  }),
+  capture: z.strictObject({
+    observation_ms: z.number().int().min(0),
+    events_observed: z.number().int().min(0),
+    events_retained: z.number().int().min(0),
+    events_dropped: z.number().int().min(0),
+    metadata_bytes_retained: z.number().int().min(0),
+    truncated: z.boolean(),
+    truncation_reasons: z.array(observationTextSchema),
+  }),
+  scripts: z.strictObject({
+    items: z.array(javascriptRuntimeScriptSchema),
+    observed_total: z.number().int().min(0),
+    excluded: z.strictObject({
+      unsupported_location: z.number().int().min(0),
+      invalid_protocol_value: z.number().int().min(0),
+    }),
+  }),
+  execution_contexts: z.array(javascriptRuntimeContextSchema),
+  directly_observed: z.array(observationTextSchema),
+  unavailable_without_instrumentation: z.array(observationTextSchema),
+  unknowns: z.array(observationTextSchema),
+  limitations: z.array(observationTextSchema),
+});
+export type JavaScriptRuntimeObservation = z.infer<
+  typeof javascriptRuntimeObservationSchema
+>;