@telorun/kernel 0.83.0 → 0.84.0

package/src/evaluation-context.ts

@@ -30,6 +30,11 @@ import {
 import { RuntimeError } from "@telorun/sdk";
 import { evalPathCovers } from "@telorun/analyzer";
 import { effectOwnerOf, executeReturnedChain } from "./effect-scope.js";
+import {
+  REDACTED,
+  redactSensitive,
+  sensitivePathsOfInstance,
+} from "./instance-sensitive-paths.js";
 import {
   classifyInitFailures,
   isDeferral,
@@ -142,6 +147,12 @@ function localDependencyNames(refs: ResourceRef[]): string[] {
  *  whole-value match is redacted. */
 const MIN_SUBSTRING_SCRUB_LEN = 5;
 
+/** A live resource instance, as opposed to the raw config value a slot held
+ *  before Phase-5 injection — the same duck-test the reference-resolving
+ *  controllers use. */
+const hasSnapshotMethod = (value: unknown): boolean =>
+  !!value && typeof (value as { snapshot?: unknown }).snapshot === "function";
+
 export function buildResolvedProperties(
   resource: ResourceManifest,
   secretValues: Set<string>,
@@ -752,6 +763,43 @@ export class EvaluationContext implements IEvaluationContext {
     return def?.status;
   }
 
+  /**
+   * The configured values a merge-form inheriting child publishes over the
+   * parent instance's reading, or undefined when the kind declares none.
+   *
+   * Such a child IS the parent instance — the inherited controller returns it
+   * verbatim — so `snapshot()` is the parent's and a field the parent never
+   * declared would be readable from nowhere. The field NAMES come from
+   * `publishedOwnFields`, stamped onto the definition at registration in the
+   * scope that declared the `extends` alias; resolving the chain here would
+   * resolve it in the READING module's scope, which may have no alias for the
+   * parent's library. Done here rather than by rebinding the instance's
+   * `snapshot()` because this is definition-derived data joined into a reading —
+   * exactly what `statusSchemaOf` already does — and a second kernel cannot
+   * rebind a trait method.
+   *
+   * Two values are withheld rather than published, both conservatively: a
+   * runtime-eval field is still a `CompiledValue` at this point (only compile
+   * paths are expanded at create), and a live instance is a collaborator rather
+   * than a reading. Publishing either would put a wrong-typed value in the CEL
+   * scope, which is the failure this overlay exists to remove.
+   */
+  private ownFieldOverlay(
+    kind: string,
+    resource: Record<string, unknown>,
+  ): Record<string, unknown> | undefined {
+    const def = this.getDefinition?.(this.resolveKindSafe(kind)) ?? this.getDefinition?.(kind);
+    const fields = (def as { publishedOwnFields?: string[] } | undefined)?.publishedOwnFields;
+    if (!fields?.length) return undefined;
+    let overlay: Record<string, unknown> | undefined;
+    for (const field of fields) {
+      const value = resource[field];
+      if (value === undefined || isCompiledValue(value) || hasSnapshotMethod(value)) continue;
+      (overlay ??= {})[field] = value;
+    }
+    return overlay;
+  }
+
   /**
    * Re-read a resource's `snapshot()` and republish it, joined with whatever
    * observed state the resource has reported. The single publication path — the
@@ -760,11 +808,14 @@ export class EvaluationContext implements IEvaluationContext {
    */
   async publishSnapshot(name: string): Promise<void> {
     const entry = this.resourceInstances.get(name) ?? this.createdInstances.get(name);
-    if (!entry?.instance.snapshot) return;
-    const snap = (await Promise.resolve(entry.instance.snapshot())) as
-      | Record<string, unknown>
-      | undefined;
+    if (!entry) return;
     const kind = entry.resource.kind as string;
+    const own = this.ownFieldOverlay(kind, entry.resource);
+    if (!entry.instance.snapshot && !own) return;
+    const snapshot = entry.instance.snapshot
+      ? ((await Promise.resolve(entry.instance.snapshot())) as Record<string, unknown> | undefined)
+      : undefined;
+    const snap = own ? { ...(snapshot ?? {}), ...own } : snapshot;
     const props = buildPublishedProps(snap, {
       kind,
       name,
@@ -1606,6 +1657,30 @@ export class EvaluationContext implements IEvaluationContext {
       : undefined;
     // Capture the root CEL scope once, on the trace's root span's terminal event.
     const rootScope = tracing && parentInvocationId === undefined ? this.traceRootScope() : undefined;
+    // What a payload may say about this call. A credential is a dispatched
+    // invocable, so its material is an invoke OUTPUT — and inputs and outputs
+    // ride the debug wire on every call under `--inspect`, i.e. every watch
+    // session, which the substring scrubbing does not reach (one call site, the
+    // resource-Created event's properties). The kind that owns the contract
+    // marks the field; nothing here knows which kind that is.
+    const hide = (detail: Record<string, unknown>): Record<string, unknown> => {
+      let out = detail;
+      for (const direction of ["inputType", "outputType"] as const) {
+        const key = direction === "inputType" ? "inputs" : "outputs";
+        if (!(key in out)) continue;
+        const paths = sensitivePathsOfInstance(instance, direction);
+        // Unknown, because the contract would not resolve — withhold the whole
+        // value rather than guess. The dispatch is about to raise that same
+        // failure with its own code.
+        if (paths === undefined) {
+          out = { ...out, [key]: REDACTED };
+          continue;
+        }
+        if (paths.length === 0) continue;
+        out = { ...out, [key]: redactSensitive(out[key], paths) };
+      }
+      return out;
+    };
     const span = (
       phase: "start" | "end",
       outcome: SpanOutcome | undefined,
@@ -1620,7 +1695,7 @@ export class EvaluationContext implements IEvaluationContext {
         "invoke",
         phase,
         outcome,
-        phase === "end" && rootScope ? { ...detail, context: rootScope } : detail,
+        phase === "end" && rootScope ? { ...hide(detail), context: rootScope } : hide(detail),
       );
     // When tracing, a derived context carries the new id down the tree so nested
     // invokes read it as their parent; it is never `=== ambient`, so the call

package/src/instance-sensitive-paths.ts

@@ -0,0 +1,123 @@
+/**
+ * Instance → the contract paths its kind marked `x-telo-sensitive`, recorded at
+ * `create()` beside the handle and the declaration.
+ *
+ * The trace site has only the instance. It cannot re-derive this: the resolved
+ * contract is compiled inside `bindContract`'s closure and dropped, the
+ * definition carries the DECLARATION rather than the resolved schema, and an
+ * instance-manifest override would be missed by re-resolving from the kind. So
+ * the answer is recorded where both halves are in hand, exactly as
+ * `instance-declaration.ts` records the other direction.
+ *
+ * TWO entries per instance, kept apart by direction, because a contract may mark
+ * a field on the way in as well as on the way out — `forceRefresh` going to a
+ * credential is not sensitive, but a signing key handed to one would be, and a
+ * single merged list would redact an input path in an output payload where it
+ * names something else entirely.
+ *
+ * Weak and one-way: paths are obtainable FROM an instance, never an instance
+ * from paths, so nothing here extends a lifetime or hands out live state.
+ * Resolution is LAZY — the paths are read through a thunk rather than eagerly,
+ * because compiling a contract at create time would make every contract-bearing
+ * kind depend on type-registration order, which is the reason the binding defers
+ * it in the first place.
+ */
+
+export type ContractDirection = "inputType" | "outputType";
+
+interface SensitiveThunks {
+  inputType?: () => string[][];
+  outputType?: () => string[][];
+}
+
+const sensitive = new WeakMap<object, SensitiveThunks>();
+
+/** Record how to obtain one direction's sensitive paths for a live instance.
+ *  First record wins, matching the handle and declaration rules: a `base:` child
+ *  IS its parent instance, and the parent's binding is the one that produced
+ *  it. */
+export function recordSensitivePaths(
+  instance: object,
+  direction: ContractDirection,
+  paths: () => string[][],
+): void {
+  const entry = sensitive.get(instance) ?? {};
+  if (entry[direction] !== undefined) return;
+  entry[direction] = paths;
+  sensitive.set(instance, entry);
+}
+
+/**
+ * The paths one direction of a live instance's contract marked sensitive.
+ *
+ * An EMPTY list means the contract marked nothing, or the kind declares no
+ * contract at all — carry the payload verbatim. `undefined` means the contract
+ * could not be resolved, so WHICH fields are sensitive is unknown and the
+ * payload must be withheld whole.
+ *
+ * Nothing is swallowed by that: resolving is exactly what the dispatch about to
+ * follow does, so the same failure surfaces from it a moment later, with its own
+ * code and its own message. What the catch avoids is a trace site becoming the
+ * place an unrelated contract defect first appears — and, far worse, emitting
+ * auth material onto the wire because a schema failed to compile.
+ */
+export function sensitivePathsOfInstance(
+  instance: unknown,
+  direction: ContractDirection,
+): string[][] | undefined {
+  if (!instance || typeof instance !== "object") return [];
+  const thunk = sensitive.get(instance as object)?.[direction];
+  if (!thunk) return [];
+  try {
+    return thunk();
+  } catch {
+    return undefined;
+  }
+}
+
+/** What a hidden value reads as. The key is KEPT and only the value replaced,
+ *  per the logging spec §14: a payload that silently loses a key reads as a
+ *  value that was never produced. */
+export const REDACTED = "[redacted]";
+
+/**
+ * `value` with the marked paths replaced by {@link REDACTED}.
+ *
+ * Copy-on-write ALONG THE PATHS ONLY, so the caller's own object — the very
+ * object being handed to a controller, or the one it just returned — is never
+ * mutated. A whole-payload clone would be the obvious alternative and is wrong
+ * twice: it costs a deep copy per span on the dispatch path, and it would
+ * rewrite live values (a stream handle, a resource instance) that only survive
+ * by identity.
+ */
+export function redactSensitive(value: unknown, paths: readonly string[][]): unknown {
+  if (paths.length === 0) return value;
+  let out = value;
+  for (const path of paths) out = redactAt(out, path, 0);
+  return out;
+}
+
+function redactAt(node: unknown, path: readonly string[], index: number): unknown {
+  if (node === null || node === undefined) return node;
+  if (index === path.length) return REDACTED;
+  const segment = path[index];
+  if (segment === "[]") {
+    return Array.isArray(node) ? node.map((element) => redactAt(element, path, index + 1)) : node;
+  }
+  // The map-value wildcard: every own key, whatever it is named. What
+  // `additionalProperties` / `patternProperties` emit, since neither carries
+  // property names to walk.
+  if (segment === "{}") {
+    if (typeof node !== "object" || Array.isArray(node)) return node;
+    const source = node as Record<string, unknown>;
+    const out: Record<string, unknown> = {};
+    for (const [key, value] of Object.entries(source)) out[key] = redactAt(value, path, index + 1);
+    return out;
+  }
+  if (typeof node !== "object" || Array.isArray(node)) return node;
+  const object = node as Record<string, unknown>;
+  // A path the value does not carry is not a defect — the contract describes
+  // what MAY be there, and an optional field is routinely absent.
+  if (!(segment in object)) return node;
+  return { ...object, [segment]: redactAt(object[segment], path, index + 1) };
+}

package/src/invocation-contract-binding.ts

@@ -5,6 +5,7 @@ import {
   type DeclaredScalarForm,
   type DeclaredScalarPath,
   defaultBearingPaths,
+  sensitivePaths,
   effectiveContractField,
   describeProjectionFailure,
   resolveSchemaProjections,
@@ -75,6 +76,9 @@ export interface BoundContract {
    *  value is normalized at, in either direction. Empty when the contract
    *  declares none. */
   scalarPaths(): DeclaredScalarPath[];
+  /** Paths the contract marked `x-telo-sensitive` — the values a trace payload
+   *  carries as `[redacted]`. Empty when the contract marks none. */
+  sensitivePaths(): string[][];
 }
 
 const CONTRACT_ERROR: Record<ContractDirection, string> = {
@@ -149,6 +153,7 @@ export function resolveBoundContract(
   let compiled: { validate(value: unknown): void } | undefined;
   let paths: string[][] | undefined;
   let scalars: DeclaredScalarPath[] | undefined;
+  let sensitive: string[][] | undefined;
 
   const resolve = (): { validate(value: unknown): void } => {
     if (compiled !== undefined) return compiled;
@@ -193,6 +198,9 @@ export function resolveBoundContract(
     const stripped = withLiveValuesSkipped(projected, factory.resolveRef);
     paths = defaultBearingPaths(stripped, factory.resolveRef);
     scalars = declaredScalarPaths(stripped, factory.resolveRef);
+    // Read off the STRIPPED schema like the other two, so a marked node behind a
+    // live value is not reported: nothing walks into a stream to redact it.
+    sensitive = sensitivePaths(stripped, factory.resolveRef);
     // Compile by NAME whenever the declaration is one, so the type's CEL
     // `rules:` are composed in — including when a stream had to be stripped, in
     // which case the stream-bearing properties are dropped from the schema the
@@ -220,6 +228,10 @@ export function resolveBoundContract(
       resolve();
       return scalars ?? [];
     },
+    sensitivePaths: () => {
+      resolve();
+      return sensitive ?? [];
+    },
   };
 }
 

package/src/kernel.ts

@@ -53,6 +53,7 @@ import { ResourceContextImpl } from "./resource-context.js";
 import { mintResourceHandle } from "./resource-handle.js";
 import { bindEffectOwner } from "./effect-scope.js";
 import { declarationOfInstance, recordInstanceDeclaration } from "./instance-declaration.js";
+import { recordSensitivePaths } from "./instance-sensitive-paths.js";
 import { nodeHostVersions } from "./host-versions.js";
 import { nodeCelHandlers } from "./cel-handlers.js";
 import { parseRef, seedInvokeSource } from "./invoke-dispatch.js";
@@ -1479,6 +1480,26 @@ export class Kernel implements IKernel {
 
     if (!runtime.length) return { instance, ctx, resource: processedResource };
 
+    // Runtime eval paths are expanded against a CALL's inputs, so they need a
+    // call. `invoke` is the only entry point that takes any — `run()` and
+    // `provide()` are parameterless — so a kind that declares one of these paths
+    // and has no `invoke()` has annotated something nothing can ever expand: the
+    // value stays a compiled expression for the life of the resource. Reported
+    // here rather than dereferenced: this used to be a non-null assertion, and it
+    // failed as `undefined is not an object (evaluating 'instance.invoke.bind')`
+    // against the kernel's own source, naming neither the kind nor the field.
+    // Method presence rather than declared capability, because the kernel
+    // dispatches on the method — a Provider that implements `invoke` is bound
+    // exactly like an Invocable.
+    if (typeof instance.invoke !== "function") {
+      throw new RuntimeError(
+        "ERR_RUNTIME_EVAL_WITHOUT_INVOKE",
+        `Kind ${resolvedKind} declares 'x-telo-eval: runtime' (at ${runtime.join(", ")}), but its resources have no invoke() — ` +
+          `runtime evaluation expands a call's inputs, and run() / provide() take none. ` +
+          `Use 'x-telo-eval: compile' for a value resolved once when the resource is created, or give the kind an invocable controller.`,
+      );
+    }
+
     // Override invoke in-place so all lifecycle methods (init/invoke/teardown/snapshot)
     // share the same `this`. A wrapper object would split identity: state mutated by
     // init() on the wrapper would be invisible to the original invoke(), which still
@@ -1487,7 +1508,7 @@ export class Kernel implements IKernel {
     // Every argument is forwarded: `invoke(inputs, ctx)` carries the
     // InvokeContext (cancellation, tracing) as its second parameter, and a
     // wrapper that declares only `inputs` silently drops it.
-    const originalInvoke = instance.invoke!.bind(instance);
+    const originalInvoke = instance.invoke.bind(instance);
     instance.invoke = async (inputs: any, ...rest: unknown[]) => {
       const expanded = evalContext.expandPaths(inputs as Record<string, unknown>, runtime);
       return (originalInvoke as (i: any, ...r: unknown[]) => Promise<unknown>)(expanded, ...rest);
@@ -1564,6 +1585,13 @@ export class Kernel implements IKernel {
     );
     if (!input && !output) return;
 
+    // Recorded here because this is the only point holding both the instance and
+    // its resolved contract — `bindContract` closes over the contract and drops
+    // it, and the trace site has only the instance. Lazily, so a contract is
+    // still compiled on first dispatch rather than at create time.
+    if (input) recordSensitivePaths(instance, "inputType", () => input.sensitivePaths());
+    if (output) recordSensitivePaths(instance, "outputType", () => output.sensitivePaths());
+
     bindContract(instance, {
       input,
       output,