@telorun/kernel 0.68.0 → 0.70.0

package/src/logging/encode-json.ts

@@ -1,4 +1,4 @@
-import { formatUnixNano, type AnyValue, type ErrorValue, type LogRecord } from "@telorun/sdk";
+import { bigIntAt, formatUnixNano, type AnyValue, type ErrorValue, type LogRecord } from "@telorun/sdk";
 
 /**
  * The `json` encoding — `kernel/specs/logging.md` §11.1. One JSON object per
@@ -83,16 +83,21 @@ function sortKeysDeep(value: AnyValue): AnyValue {
 }
 
 function makeReplacer(encodeBytes: BytesEncoder) {
-  return function replacer(this: unknown, _key: string, value: unknown): unknown {
-    if (typeof value === "bigint") {
-      // Values beyond 2^53 lose precision in a JS receiver, so they degrade to a
-      // decimal string rather than to a wrong number — the same reasoning OTLP
-      // gives for quoting its 64-bit fields.
-      return value >= BigInt(Number.MIN_SAFE_INTEGER) && value <= BigInt(Number.MAX_SAFE_INTEGER)
-        ? Number(value)
-        : value.toString();
+  return function replacer(this: unknown, key: string, value: unknown): unknown {
+    // Read the BigInt off the HOLDER, not off `value`: `BigInt.prototype.toJSON`
+    // has already rewritten it to the exact-digits form every other JSON boundary
+    // wants (see `enableBigIntJson`). A log record is the one destination where
+    // that is wrong — a value beyond 2^53 loses precision in a JS receiver, so it
+    // degrades to a decimal string rather than to a wrong number, the same
+    // reasoning OTLP gives for quoting its 64-bit fields.
+    const source = bigIntAt(this, key);
+    if (source !== undefined) {
+      return source >= MIN_SAFE && source <= MAX_SAFE ? Number(source) : source.toString();
     }
     if (value instanceof Uint8Array) return encodeBytes(value);
     return value;
   };
 }
+
+const MIN_SAFE = BigInt(Number.MIN_SAFE_INTEGER);
+const MAX_SAFE = BigInt(Number.MAX_SAFE_INTEGER);

package/src/logging/encode-pretty.ts

@@ -1,4 +1,4 @@
-import { severityFloor, type AnyValue, type ErrorValue, type LogRecord } from "@telorun/sdk";
+import { bigIntAt, severityFloor, type AnyValue, type ErrorValue, type LogRecord } from "@telorun/sdk";
 
 /**
  * The `pretty` encoding — `kernel/specs/logging.md` §11.2. For humans on a
@@ -90,8 +90,17 @@ function quoteIfNeeded(text: string): string {
   return /[\s"=]/.test(text) ? JSON.stringify(text) : text;
 }
 
-function jsonSafe(_key: string, value: unknown): unknown {
-  if (typeof value === "bigint") return value.toString();
+function jsonSafe(this: unknown, key: string, value: unknown): unknown {
+  // Read the integer off the HOLDER, not off `value`: `BigInt.prototype.toJSON`
+  // (see `enableBigIntJson`) runs BEFORE a replacer, so by the time this is
+  // called a wide integer is already the exact-digits form every wire encoding
+  // wants. This console encoding renders it as a decimal string instead, and
+  // matching on `typeof value === "bigint"` would silently stop doing so —
+  // a changed encoding, not an error. Reading the holder keeps the rendering
+  // identical whether or not the patch is installed, which matters because a
+  // test can call this encoder outside a booted kernel.
+  const source = bigIntAt(this, key);
+  if (source !== undefined) return source.toString();
   if (value instanceof Uint8Array) return `<${value.byteLength} bytes>`;
   return value;
 }

package/src/manifest-schemas.ts

@@ -2,7 +2,7 @@ import AjvModule from "ajv";
 import addFormats from "ajv-formats";
 // One definition of the `status:` block's shape, shared with `telo check` — the
 // `required:` restriction is reported by the analyzer, which can name the fix.
-import { OBSERVED_STATE_SCHEMA } from "@telorun/analyzer";
+import { binaryKeyword, OBSERVED_STATE_SCHEMA } from "@telorun/analyzer";
 const Ajv = AjvModule.default ?? AjvModule;
 
 // Re-export the shared ResourceRef fragment from the templating package
@@ -177,6 +177,7 @@ export const ResourceAbstractSchema = {
 };
 
 const ajv = new Ajv({ allErrors: true, strict: false });
+ajv.addKeyword(binaryKeyword());
 addFormats.default(ajv);
 
 // Lazy-compile validator: the AJV codegen cost (≈10–15 ms for these

package/src/observed-state.ts

@@ -1,3 +1,4 @@
+import { binaryKeyword } from "@telorun/analyzer";
 import AjvModule from "ajv";
 import { detachSnapshotValue, OBSERVED_STATE_KEY, RuntimeError } from "@telorun/sdk";
 
@@ -57,6 +58,7 @@ function mark(target: Record<string, unknown>, info: ObservedStateInfo): void {
 }
 
 const ajv = new Ajv({ allErrors: true, strict: false });
+ajv.addKeyword(binaryKeyword());
 // Compiling a status schema costs ~ms and a resource may report repeatedly, so
 // keep the validator keyed on the schema object it came from. The kind's folded
 // `status:` is stamped once at registration, so this hits.

package/src/resource-context.ts

@@ -28,10 +28,12 @@ import {
   type TypeRule,
   type ZoneEntry,
 } from "@telorun/sdk";
+import { binaryKeyword } from "@telorun/analyzer";
 import { isRefSentinel } from "@telorun/templating";
 import { ZoneContext } from "./zone-context.js";
 import * as path from "path";
 import { pathToFileURL } from "url";
+import { withBigIntsAsNumbers } from "./bigint-schema-view.js";
 import type { ModuleArtifact } from "./bundle/module-artifact.js";
 import { hostEnv } from "./host-env.js";
 import type { LoggingHost } from "./logging/logging-host.js";
@@ -73,6 +75,12 @@ export class ResourceContextImpl implements ResourceContext {
    *  eagerly for every context would allocate per resource for nothing. */
   #log: Logger | undefined;
 
+  /** The resolved kind. It cannot come from `metadata`, which is the resource's
+   *  metadata BLOCK — `kind` is its sibling, not its member, so reading
+   *  `metadata.kind` yielded `undefined` and every controller record went out
+   *  with no resource identity at all (§7.3). */
+  #resolvedKind: string | undefined;
+
   /**
    * The resource's structured logger, stamped with its identity, module, and
    * import-alias scope so a record identifies *which instance* emitted it — the
@@ -81,8 +89,8 @@ export class ResourceContextImpl implements ResourceContext {
    */
   get log(): Logger {
     if (!this.#log) {
-      const kind = this.metadata?.kind as string | undefined;
-      const name = this.metadata?.metadata?.name as string | undefined;
+      const kind = this.#resolvedKind;
+      const name = this.metadata?.name as string | undefined;
       const resource =
         kind && name
           ? { kind, name, id: `${this.ownerPrefix}${kind}.${name}` }
@@ -149,7 +157,17 @@ export class ResourceContextImpl implements ResourceContext {
      * dispatch fails.
      */
     private readonly owningContext: IEvaluationContext = moduleContext,
+    /**
+     * The resolved kind, known long before `create()` runs. Passed here rather
+     * than waited for at `bindResourceIdentity` so `ctx.log` carries resource
+     * identity from the moment the context exists: a controller that captures
+     * `ctx.log` in its constructor — the natural thing to do when the logger is
+     * handed to a helper — would otherwise hold an identity-less logger for the
+     * resource's whole life, and nothing would report that it had.
+     */
+    resolvedKind?: string,
   ) {
+    this.#resolvedKind = resolvedKind;
     // `ctx.env` is the sanctioned host-env channel for controllers — always the
     // real environment (kernel passes its snapshot), never the locked Proxy.
     this.env = env ?? hostEnv();
@@ -301,6 +319,7 @@ export class ResourceContextImpl implements ResourceContext {
     for (const kw of ["x-telo-ref", "x-telo-scope", "x-telo-context", "x-telo-schema-from"]) {
       ajv.addKeyword(kw);
     }
+    ajv.addKeyword(binaryKeyword());
     const validate = ajv.compile(
       "type" in schema && typeof schema.type === "string"
         ? schema
@@ -311,7 +330,11 @@ export class ResourceContextImpl implements ResourceContext {
             additionalProperties: false,
           },
     );
-    const isValid = validate(stripCompiledValues(value));
+    // A BigInt-normalized view: AJV reads `integer` as `typeof == "number"`, so a
+    // CEL integer (int64) would be rejected at a slot it satisfies. This validator
+    // runs without `useDefaults` and already checks a derived value, so there is
+    // nothing to merge back. See `bigint-schema-view.ts`.
+    const isValid = validate(withBigIntsAsNumbers(stripCompiledValues(value)));
     if (!isValid) {
       throw new RuntimeError(
         "ERR_INVALID_VALUE",
@@ -341,6 +364,10 @@ export class ResourceContextImpl implements ResourceContext {
     manifest: Record<string, unknown>,
   ): void {
     this.#self = handle;
+    // The kind is NOT restated here. It is set at construction — the single
+    // production site always has it — and `#log` is memoized on first access, so
+    // a late assignment could not reach a logger a controller already holds. A
+    // fallback here would read as a guarantee it cannot provide.
     this.#zones = new ZoneContext({
       resourceName: (this.metadata?.name as string) ?? "<unnamed>",
       resolvedKind,
@@ -418,10 +445,16 @@ export class ResourceContextImpl implements ResourceContext {
     // settlement is already observed here.
     const tracked = this.owningContext
       .runDetached(fn) // bare scope-detach primitive
-      .catch(async (err: unknown) => {
-        const detail =
-          err instanceof Error ? { name: err.name, message: err.message } : { message: String(err) };
-        await this.emitEvent("background.task.error", { resource: this.metadata.name, error: detail });
+      .catch((err: unknown) => {
+        // A detached task has no caller to throw to, so this record is the only
+        // report. It replaces the bus event rather than joining it: `eventName`
+        // IS the bridge to the event bus (§4), and a record already reaches every
+        // sink including the debug wire, so emitting both would ship two copies
+        // of one fact with two payload shapes to keep in step.
+        this.log.error("Detached task failed", undefined, {
+          error: err,
+          eventName: "background.task.error",
+        });
       })
       .finally(() => {
         this.pendingDetached.delete(tracked);
@@ -446,10 +479,12 @@ export class ResourceContextImpl implements ResourceContext {
     await Promise.race([Promise.allSettled([...this.pendingDetached]), timeout]);
     if (timer) clearTimeout(timer);
     if (this.pendingDetached.size > 0) {
-      await this.emitEvent("background.task.abandoned", {
-        resource: this.metadata.name,
-        count: this.pendingDetached.size,
-      });
+      this.log.warn(
+        `Abandoned ${this.pendingDetached.size} background task(s) after waiting ` +
+          `${DETACHED_DRAIN_TIMEOUT_MS}ms for them to drain`,
+        { "telo.detached.abandoned": this.pendingDetached.size },
+        { eventName: "background.task.abandoned" },
+      );
     }
   }
 

package/src/schema-validator.ts

@@ -7,17 +7,16 @@ import { createHash } from "node:crypto";
 import * as fs from "node:fs";
 import { createRequire } from "node:module";
 import * as path from "node:path";
+import { binaryKeyword, X_TELO_BINARY } from "@telorun/analyzer";
+import { mergeFilledDefaults, withBigIntsAsNumbers } from "./bigint-schema-view.js";
 import { formatAjvErrors } from "./manifest-schemas.js";
 
-/** Render a value for an error message without ever throwing.
- *
- *  `JSON.stringify` refuses BigInt, and CEL evaluates an integer literal to one —
- *  so serializing the offending data threw from inside the message template and
- *  the thrown stringify error REPLACED the validation failure. The author was
- *  told "cannot serialize BigInt" instead of which field was wrong. */
+/** Render a value for an error message without ever throwing — the offending
+ *  data may be cyclic, and a throw here would REPLACE the validation failure
+ *  with an unrelated error naming no field. */
 function describeValue(data: unknown): string {
   try {
-    return JSON.stringify(data, (_k, v) => (typeof v === "bigint" ? `${v}` : v)) ?? String(data);
+    return JSON.stringify(data) ?? String(data);
   } catch {
     return String(data);
   }
@@ -165,13 +164,23 @@ const NAME_KEYED_SCHEMA_KEYWORDS = new Set([
  *  two schemas that differ only there hash alike. */
 const DATA_VALUE_KEYWORDS = new Set(["const", "default", "enum", "examples"]);
 
+/** Annotations that DO emit validation code, and so must survive the strip and stay
+ *  in the cache key. `x-telo-binary` is the first: bytes have no JSON Schema type,
+ *  so the keyword is the only thing standing between a byte slot and "accepts any
+ *  object". Stripping it would silently reduce the slot to an empty schema — the
+ *  precise regression the annotation was introduced to close — and, because the key
+ *  is meant to describe the compiled validator, a keyword that changes the validator
+ *  belongs in it. */
+const VALIDATING_ANNOTATIONS = new Set([X_TELO_BINARY]);
+
 /** Deep-clone `schema` without its `x-telo-*` annotations — applied, like
  *  {@link collapseSentinelsToSource}, before both AJV compilation and cache
  *  hashing.
  *
- *  Every `x-telo-*` keyword is analyzer/editor metadata: AJV runs `strict:
- *  false` and registers the known ones as no-op keywords, so none of them emits
- *  a single line of validation code. Leaving them in the hashed form makes the
+ *  Almost every `x-telo-*` keyword is analyzer/editor metadata: AJV runs `strict:
+ *  false` and registers the known ones as no-op keywords, so they emit no
+ *  validation code. {@link VALIDATING_ANNOTATIONS} is the exception and is kept —
+ *  see the note there. Leaving the rest in the hashed form makes the
  *  cache key sensitive to differences that cannot change what the validator
  *  does — and one such difference is real and systematic. The analyzer rewrites
  *  `x-telo-ref.kind` to its canonical `<module>.<Kind>` in the declaring scope
@@ -193,7 +202,7 @@ function stripTeloAnnotations(value: unknown, nameKeyed = false): unknown {
   if (!value || typeof value !== "object") return value;
   const out: Record<string, unknown> = {};
   for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
-    if (!nameKeyed && k.startsWith("x-telo-")) continue;
+    if (!nameKeyed && k.startsWith("x-telo-") && !VALIDATING_ANNOTATIONS.has(k)) continue;
     // A data-bearing keyword's value is carried over verbatim; a name-keyed
     // map's VALUES are schema nodes again, so only its keys are exempt.
     out[k] =
@@ -265,6 +274,11 @@ export class SchemaValidator {
     ]) {
       this.ajv.addKeyword(kw);
     }
+    // Not a no-op like the rest: bytes have no JSON Schema type, so this keyword IS
+    // the check. Defined as codegen in the analyzer so it inlines into the
+    // standalone validators compiled and cached below, rather than needing the
+    // implementation present at load.
+    this.ajv.addKeyword(binaryKeyword());
     // Register the shared manifest root so module schemas can
     // `$ref: "telo://manifest#/$defs/ResourceRef"` without each manifest
     // bundling its own copy. Mirrors the analyzer's createAjv().
@@ -383,19 +397,32 @@ export class SchemaValidator {
     const validate = this.compileAjvOrLoadCached(sanitized, hash, persist);
     if (persist) this.persistedHashes.add(hash);
 
+    // AJV's type check is `typeof data == "number"`, so a CEL integer — a BigInt —
+    // is rejected at an `integer` slot no matter what the author writes. Check a
+    // normalized VIEW instead and merge the `useDefaults` fills back, so the value
+    // that reaches the controller keeps its 64-bit range. `withBigIntsAsNumbers`
+    // returns the same reference when there was nothing to normalize, which is what
+    // keeps the BigInt-free path byte-identical to a plain `validate(data)`.
+    const check = (data: any): boolean => {
+      const view = withBigIntsAsNumbers(data);
+      const ok = validate(view);
+      if (ok && view !== data) mergeFilledDefaults(data, view);
+      return ok;
+    };
+
     const validator = {
       validate: (data: any) => {
-        const isValid = validate(data);
-        if (!isValid) {
+        if (!check(data)) {
+          // Reports `data`, not the normalized view: the view renders a wide
+          // integer through a double, so the digits it prints for the offending
+          // value would not be the ones the author wrote.
           throw new RuntimeError(
             "ERR_RESOURCE_SCHEMA_VALIDATION_FAILED",
             `Invalid value passed: ${describeValue(data)}. Error: ${formatAjvErrors(validate.errors)}`,
           );
         }
       },
-      isValid: (data: any) => {
-        return validate(data);
-      },
+      isValid: (data: any) => check(data),
     };
 
     this.hashCache.set(hash, validator);