@ngockhoale/ukit 3.0.11 → 3.1.0

package/src/core/agentRuntime/diagnostics.js

@@ -14,6 +14,13 @@
  * Read-only guarantee: this module performs no writes, spawns, signals,
  * or enqueues. Journal + contract are the only inputs. It performs no
  * config reads (same convention as eventStore.js).
+ *
+ * DF2-FR07 (TASK-008): this module is ALSO the diagnostics-side emit
+ * surface — `emitModelAttempt` and `emitVerificationCompleted` turn a
+ * finished model attempt / verification gate outcome into canonical
+ * recorder records parented onto the caller's run span ctx. Emit helpers
+ * are synchronous, never throw, and never write to journals — the
+ * read-only contract above still holds for the two readers.
  */
 
 import { promises as fs } from 'node:fs';
@@ -26,6 +33,7 @@ import {
   validateTransition,
 } from './contract.js';
 import { readJournal, EventStoreError } from './eventStore.js';
+import { makeSpanContext, emitSpanRecord, typedResource, registryCode } from './telemetry.js';
 
 export class DiagnosticsError extends Error {
   constructor(code, message) {
@@ -242,3 +250,99 @@ export async function replayOperation(dir, operationId, _opts = {}) {
     gaps: Object.freeze(gaps),
   });
 }
+
+// --- DF2-FR07: model.* / verification.completed emit helpers ---------------
+// The emit surface lives here (not on the read path): callers that own a
+// model attempt or a verification gate call these with the run's span ctx
+// (from supervisor.start().telemetry or a parent's ctx) so every record
+// lands on the run's trace_id with a resolvable parent_span_id.
+// DF-FR08 resource honesty is enforced by typedResource — absent usage
+// is {value:null, source:'UNKNOWN'} + telemetry_complete:false, never 0.
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function safeDurationMs(value) {
+  return typeof value === 'number' && Number.isFinite(value) && value >= 0
+    ? Math.max(value, 1e-6)
+    : null;
+}
+
+/**
+ * Emit a `model.started` + `model.completed`/`model.failed` span pair for
+ * one model attempt. `ctx` is the parent (run) span ctx — the attempt
+ * span is a child of it. Returns the child ctx; null when ctx missing.
+ *
+ * @param {object} recorder live recorder (emit only — never flushed here)
+ * @param {object} args
+ * @param {object} args.ctx parent span ctx {trace_id, span_id, execution_id, agent_id?, nowNs?}
+ * @param {boolean} [args.ok=true] whether the attempt succeeded
+ * @param {number} [args.durationMs] caller-measured attempt duration (ms)
+ * @param {number} [args.attemptIndex] 1-based attempt index (retries >1)
+ * @param {{value:number|null, source:string}} [args.resource] DF-FR08 usage
+ * @param {string} [args.errorCode] registry reason code for failures
+ */
+export function emitModelAttempt(recorder, {
+  ctx,
+  ok = true,
+  durationMs: duration,
+  attemptIndex,
+  resource,
+  errorCode,
+} = {}) {
+  if (recorder == null || typeof recorder.emit !== 'function' || !isPlainObject(ctx)) {
+    return null;
+  }
+  const telemetry = { recorder };
+  const span = makeSpanContext(ctx);
+  const payload = { operation: 'model' };
+  if (Number.isInteger(attemptIndex)) payload.attempt_index = attemptIndex;
+  emitSpanRecord(telemetry, span, 'model.started', payload);
+  const end = { ...payload };
+  const measured = safeDurationMs(duration);
+  if (measured !== null) end.duration_ms = measured;
+  const typed = typedResource(resource);
+  end.resource = typed.resource;
+  end.telemetry_complete = typed.complete;
+  if (ok !== true) end.error_code = registryCode(errorCode);
+  emitSpanRecord(telemetry, span, ok === true ? 'model.completed' : 'model.failed', end);
+  return span;
+}
+
+/**
+ * Emit `verification.completed` for a verification gate that ran to a
+ * verdict — outcome is the gate's typed verdict string (never raw
+ * output), reason_code only from the frozen registry.
+ *
+ * @param {object} recorder
+ * @param {object} args
+ * @param {object} args.ctx parent span ctx
+ * @param {string} args.outcome verdict code ('passed'|'failed'|'indeterminate'|gate verdict)
+ * @param {number} [args.durationMs] gate duration in ms when measured
+ * @param {string} [args.reasonCode] registry code explaining the outcome
+ * @param {number} [args.attempt] verification attempt count
+ */
+export function emitVerificationCompleted(recorder, {
+  ctx,
+  outcome,
+  durationMs: duration,
+  reasonCode,
+  attempt,
+} = {}) {
+  if (recorder == null || typeof recorder.emit !== 'function' || !isPlainObject(ctx)) {
+    return null;
+  }
+  const telemetry = { recorder };
+  const span = makeSpanContext(ctx);
+  const payload = {
+    operation: 'verification',
+    outcome: typeof outcome === 'string' && outcome.length > 0 ? outcome : 'unknown',
+  };
+  const measured = safeDurationMs(duration);
+  if (measured !== null) payload.duration_ms = measured;
+  if (reasonCode != null) payload.reason_code = registryCode(reasonCode);
+  if (Number.isInteger(attempt)) payload.attempt = attempt;
+  emitSpanRecord(telemetry, span, 'verification.completed', payload);
+  return span;
+}

package/src/core/agentRuntime/supervisor.js

@@ -34,6 +34,15 @@ import {
 import { classifyObservation } from './liveness.js';
 import { createArtifactWriter } from './artifacts.js';
 import { reconcileOwnedOperations } from './recovery.js';
+import { beginToolSpan, endToolSpan } from './adapters.js';
+import {
+  resolveTelemetry,
+  newRunContext,
+  emitSpanRecord,
+  durationMs,
+  reasonCodeForFailure,
+  projectRootFromRuntimeDir,
+} from './telemetry.js';
 
 const SUPERVISOR_FLAG = 'decisionRuntime.supervisor.stage';
 // G6 (DR-09): `decisionRuntime.promotion.stage` — absent/malformed → 'off';
@@ -108,6 +117,66 @@ export function createSupervisor(opts = {}) {
   const resourcesFn = typeof opts.resourcesFn === 'function' ? opts.resourcesFn : () => ({});
   // Bounded receipt log — shadow-stage evidence only, never fs.
   const WAIT_RECEIPT_CAP = 128;
+
+  // DF2-FR07 telemetry lane — resolved once at creation; null = emit path
+  // never runs (zero per-event cost when no recorder exists). Stage gating
+  // stays inside recorder.emit per record (kill switch is live-read).
+  const telemetry = resolveTelemetry({
+    recorder: opts.telemetry?.recorder,
+    projectRoot: opts.telemetry?.projectRoot ?? projectRootFromRuntimeDir(runtimeDir),
+    config: opts.config ?? null,
+    env: opts.env,
+    clock: opts.telemetry?.clock,
+  });
+
+  /** Open the run's execution root span (emits execution.started). */
+  function beginExecutionSpan(spec) {
+    const ctx = newRunContext(telemetry, { traceId: spec?.traceId });
+    emitSpanRecord(telemetry, ctx, 'execution.started', {
+      operation: spec?.operationId ?? 'run',
+      duration_ms: null,
+    });
+    return ctx;
+  }
+
+  /** Close the run root span: completed | failed | blocked. */
+  function endExecutionSpan(ctx, status, payload = {}) {
+    if (!ctx) return;
+    emitSpanRecord(telemetry, ctx, `execution.${status}`, {
+      operation: payload.operation ?? ctx.operation ?? 'run',
+      duration_ms: durationMs(ctx.start_ns, telemetry.nowNs()),
+      ...payload,
+    });
+  }
+
+  /**
+   * Close tool + execution spans exactly once per op. `status` is the
+   * terminal outcome ('completed'|'failed'|'blocked'); `info` carries
+   * exit/cancel detail mapped onto the frozen reason vocabulary.
+   */
+  function closeOpSpans(op, status, { errorCode, reasonCode, exitCode } = {}) {
+    if (!telemetry || !op.telemetryCtx || op.spansClosed) return;
+    op.spansClosed = true;
+    // A blocked execution never spawned a tool — its tool span either
+    // does not exist or failed before the gate; 'blocked' only describes
+    // the execution end record.
+    const toolFailed = status === 'failed';
+    if (op.toolCtx) {
+      endToolSpan(telemetry, op.toolCtx, {
+        status: toolFailed ? 'failed' : 'completed',
+        errorCode: toolFailed ? errorCode : undefined,
+        toolName: op.spec?.toolName ?? op.spec?.sideEffectClass,
+        operationId: op.id,
+        exitCode,
+      });
+    }
+    endExecutionSpan(op.telemetryCtx, status, {
+      operation: op.id,
+      ...(toolFailed && errorCode != null ? { error_code: errorCode } : {}),
+      ...(reasonCode != null ? { reason_code: reasonCode } : {}),
+      ...(Number.isInteger(exitCode) ? { exit_code: exitCode } : {}),
+    });
+  }
   const waitReceipts = [];
 
   function recordWaitReceipt(entry) {
@@ -281,6 +350,10 @@ export function createSupervisor(opts = {}) {
             fencingEpoch,
             ownerEpoch,
           });
+          closeOpSpans(op, 'failed', {
+            errorCode: reasonCodeForFailure({ cancelReason: op.cancelReason ?? 'cancel_requested' }),
+            exitCode: op.exitInfo?.code,
+          });
         });
       }
     }, limits.killGraceMs));
@@ -389,6 +462,23 @@ export function createSupervisor(opts = {}) {
     const event = makeEvent(op, 'operation.transition', { from, to, ...extra }, op.artifactRefs);
     await append(runtimeDir, event);
     await writeOperationState(runtimeDir, op.id, { state: to, fencingEpoch, ownerEpoch });
+    // DF2-FR07: terminal transition committed — close tool + execution
+    // spans with the same outcome. Cancelled is a failed run with a
+    // USER_CANCELLED/TOOL_TIMEOUT code, never a silent open span.
+    if (to === 'completed') {
+      closeOpSpans(op, 'completed', { exitCode: op.exitInfo?.code });
+    } else {
+      closeOpSpans(op, 'failed', {
+        errorCode: reasonCodeForFailure({
+          cancelReason: to === 'cancelled' ? (op.cancelReason ?? 'cancel_requested') : undefined,
+          exitCode: op.exitInfo?.code,
+          signal: op.exitInfo?.signal,
+          errno: artErr,
+          code: artErr != null ? undefined : (op.cancelRequested ? 'cancelled' : 'exit_nonzero'),
+        }),
+        exitCode: op.exitInfo?.code,
+      });
+    }
   }
 
   function onExit(op, code, signal) {
@@ -411,10 +501,23 @@ export function createSupervisor(opts = {}) {
      * whole tree via `-pgid`.
      */
     async start(spec, policy = {}) {
+      // DF2-FR07: the run's execution root span opens at supervisor entry —
+      // BEFORE the preflight gates so a refused launch still lands an
+      // execution.blocked record on a real trace (flight recorder keeps
+      // refusals, not just runs).
+      const ctx = telemetry ? beginExecutionSpan(spec) : null;
       if (closed || launchesDisabled || !enabledByConfig()) {
+        endExecutionSpan(ctx, 'blocked', {
+          operation: spec?.operationId ?? 'run',
+          reason_code: 'GATE_BLOCKED',
+        });
         return unsupported('launch_disabled');
       }
       if (!specIsValid(spec)) {
+        endExecutionSpan(ctx, 'blocked', {
+          operation: 'run',
+          reason_code: 'SCHEMA_MISMATCH',
+        });
         return unsupported('invalid_spec');
       }
       // G6 promotion consult — shadow evaluates+records a receipt; served
@@ -447,6 +550,7 @@ export function createSupervisor(opts = {}) {
         artifacts: null,
         timers: new Set(),
       };
+      op.telemetryCtx = ctx;
       operations.set(op.id, op);
 
       await transition(op, 'starting', {
@@ -455,6 +559,16 @@ export function createSupervisor(opts = {}) {
       });
 
       let proc;
+      // DF2-FR07: the owned child process IS this run's tool invocation —
+      // tool.started opens right before spawn so a spawn throw still
+      // closes it as tool.failed (never an orphaned open span).
+      if (telemetry) {
+        op.toolCtx = beginToolSpan(telemetry, ctx, {
+          toolName: spec.toolName ?? spec.sideEffectClass,
+          operationId: spec.operationId,
+          attempt: spec.attempt,
+        });
+      }
       try {
         const argv = Array.isArray(spec.argv) && spec.argv.length > 0
           ? spec.argv
@@ -469,6 +583,19 @@ export function createSupervisor(opts = {}) {
         await transition(op, 'failed', {
           error: { code: 'spawn_failed', message: String(err?.message ?? err) },
         });
+        if (telemetry) {
+          const code = reasonCodeForFailure({ code: 'spawn_failed', errno: err?.code });
+          endToolSpan(telemetry, op.toolCtx, {
+            status: 'failed',
+            errorCode: code,
+            toolName: spec.toolName ?? spec.sideEffectClass,
+            operationId: spec.operationId,
+          });
+          endExecutionSpan(ctx, 'failed', {
+            operation: spec.operationId,
+            error_code: code,
+          });
+        }
         return { ok: false, code: 'spawn_failed' };
       }
 
@@ -511,6 +638,16 @@ export function createSupervisor(opts = {}) {
         get currentState() {
           return op.state;
         },
+        // DF2-FR07: the run's span ctx propagates to callers so tool/model/
+        // verification emits parent onto this span — the span-context
+        // convention the task's Interfaces contract specifies.
+        telemetry: ctx ? {
+          trace_id: ctx.trace_id,
+          span_id: ctx.span_id,
+          execution_id: ctx.execution_id,
+          ...(ctx.agent_id ? { agent_id: ctx.agent_id } : {}),
+          nowNs: ctx.nowNs,
+        } : null,
       };
     },
 

package/src/core/agentRuntime/telemetry.js

@@ -0,0 +1,204 @@
+/**
+ * agentRuntime/telemetry.js (TASK-008, SPEC §5 DF2-FR07, DF-FR08) —
+ * span-context plumbing for live agentRuntime telemetry.
+ *
+ *   resolveTelemetry({ recorder, config, env }) → ctx | null
+ *   makeSpanContext(ctx, parentSpan) → child ctx
+ *   emitSpanRecord(telemetry, ctx, semanticName, payload) → EmitResult
+ *   durationMs(startNs, nowNs) → positive ms | null
+ *   projectRootFromRuntimeDir(runtimeDir) → projectRoot | null
+ *
+ * Contracts:
+ *   - Emission is fire-and-forget: every helper is synchronous, wraps
+ *     recorder.emit in try/catch, and NEVER throws into task execution —
+ *     a throwing recorder is a telemetry loss, not a runtime failure.
+ *   - Span context is the run's wiring convention: {trace_id, span_id,
+ *     parent_span_id, execution_id, agent_id?, nowNs}. A child ctx is
+ *     made only from a real parent span — parent_span_id always resolves
+ *     to a span emitted in the same trace (validator causality rule).
+ *   - DF-FR08: model/tool end records carry typed resource provenance
+ *     {value, source}; absent usage stays {value:null, source:'UNKNOWN'}
+ *     with telemetry_complete:false — never 0, never fabricated.
+ *   - agent_id (SPEC §14): UKIT_AGENT_ID env, else config.agent.id, else
+ *     the field is ABSENT — never an empty string.
+ *   - Stage 'off' is enforced inside recorder.emit per record; helpers
+ *     never pre-judge the stage.
+ */
+
+import crypto from 'node:crypto';
+import path from 'node:path';
+
+import { getRecorder } from '../observability/emit/lifecycle.js';
+import { RESOURCE_SOURCES } from '../observability/schema/constants.js';
+import { REASON_CODES } from '../observability/schema/registry.js';
+
+/** Monotonic nanoseconds — BigInt where available (process.hrtime). */
+export function nowNs() {
+  return typeof process.hrtime?.bigint === 'function'
+    ? process.hrtime.bigint()
+    : BigInt(Math.round(performance.now() * 1e6));
+}
+
+/**
+ * Measured span duration in ms. Sub-millisecond spans still report a
+ * positive duration — a closed span always took real time, so 0 would
+ * read as "unmeasured" downstream (summary.js treats duration>0 as real).
+ */
+export function durationMs(startNs, endNs) {
+  if (typeof startNs !== 'bigint' || typeof endNs !== 'bigint') return null;
+  const delta = Number(endNs - startNs) / 1e6;
+  if (!Number.isFinite(delta) || delta < 0) return null;
+  return Math.max(delta, 1e-6);
+}
+
+function isNonEmptyString(value) {
+  return typeof value === 'string' && value.length > 0;
+}
+
+/**
+ * agent_id source (SPEC §14): UKIT_AGENT_ID env first, config.agent.id
+ * second, absent otherwise. The field is omitted entirely — never ''.
+ */
+export function resolveAgentId({ config, env } = {}) {
+  const source = env && typeof env === 'object' ? env : process.env;
+  if (isNonEmptyString(source?.UKIT_AGENT_ID)) return source.UKIT_AGENT_ID;
+  const fromConfig = config?.agent?.id;
+  return isNonEmptyString(fromConfig) ? fromConfig : null;
+}
+
+/**
+ * `.ukit/storage/agent-runtime[/...]` → project root. Returns null when
+ * the layout does not match (tests, foreign dirs) — the caller then
+ * relies on an explicit recorder instead of guessing a root.
+ */
+export function projectRootFromRuntimeDir(runtimeDir) {
+  if (typeof runtimeDir !== 'string' || runtimeDir === '') return null;
+  const resolved = path.resolve(runtimeDir);
+  let dir = resolved;
+  for (let i = 0; i < 8; i += 1) {
+    if (path.basename(dir) === '.ukit') return path.dirname(dir);
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+
+/**
+ * Build the telemetry lane for one supervisor/adapter site. Returns null
+ * when there is no recorder — the lane is then a guaranteed no-op with
+ * zero per-event cost (DF2-FR07 stage-off = zero records AND no emit
+ * path work). `recorder` wins; otherwise getRecorder memoizes per root.
+ */
+export function resolveTelemetry({ recorder, projectRoot, config, env, clock } = {}) {
+  const rec = recorder ?? (projectRoot ? getRecorder({ projectRoot, config }) : null);
+  if (rec == null || typeof rec.emit !== 'function' || rec.disabled === true) return null;
+  const agent_id = resolveAgentId({ config, env });
+  return {
+    recorder: rec,
+    agent_id,
+    nowNs: clock && typeof clock.nowNs === 'function' ? clock.nowNs.bind(clock) : nowNs,
+  };
+}
+
+/** Root span context for one run — the trace_id owner. */
+export function newRunContext(telemetry, { traceId } = {}) {
+  const trace_id = isNonEmptyString(traceId)
+    ? traceId
+    : `trace-${crypto.randomUUID()}`;
+  return {
+    trace_id,
+    span_id: `span-${crypto.randomUUID()}`,
+    parent_span_id: null,
+    execution_id: `exec-${crypto.randomUUID()}`,
+    ...(telemetry.agent_id ? { agent_id: telemetry.agent_id } : {}),
+    nowNs: telemetry.nowNs,
+    start_ns: telemetry.nowNs(),
+  };
+}
+
+/** Child ctx under a real parent span (tool/model/verification). */
+export function makeSpanContext(parent) {
+  return {
+    trace_id: parent.trace_id,
+    span_id: `span-${crypto.randomUUID()}`,
+    parent_span_id: parent.span_id,
+    execution_id: parent.execution_id,
+    ...(parent.agent_id ? { agent_id: parent.agent_id } : {}),
+    nowNs: parent.nowNs,
+    start_ns: parent.nowNs ? parent.nowNs() : undefined,
+  };
+}
+
+/**
+ * Emit one span/event record. Envelope ids come from ctx verbatim; the
+ * recorder fills record_id/sequence/timestamps and the registry privacy
+ * floor. Never throws — a throwing recorder returns a typed drop.
+ */
+export function emitSpanRecord(telemetry, ctx, semanticName, payload) {
+  try {
+    return telemetry.recorder.emit({
+      semantic_name: semanticName,
+      trace_id: ctx.trace_id,
+      span_id: ctx.span_id,
+      parent_span_id: ctx.parent_span_id ?? null,
+      execution_id: ctx.execution_id,
+      ...(ctx.agent_id ? { agent_id: ctx.agent_id } : {}),
+      payload: payload ?? {},
+    });
+  } catch {
+    return { status: 'dropped', reason: 'emit-threw' };
+  }
+}
+
+/**
+ * Map a supervisor failure/cancel code onto the frozen REASON_CODES
+ * vocabulary (task test 3: error_code is UPPER_SNAKE from the registry,
+ * never free text). Unclassifiable causes stay HOST_BLIND — the honest
+ * "we do not have a code" code — rather than a fabricated reason.
+ */
+export function reasonCodeForFailure({ exitCode, signal, code, errno, cancelReason } = {}) {
+  if (errno === 'EACCES' || errno === 'EPERM') return 'PERMISSION_DENIED';
+  if (errno === 'ENOSPC') return 'DISK_FULL';
+  if (code === 'spawn_failed') return 'HOST_BLIND';
+  if (code === 'launch_disabled') return 'GATE_BLOCKED';
+  if (code === 'invalid_spec') return 'SCHEMA_MISMATCH';
+  if (cancelReason === 'wall_timeout' || cancelReason === 'stalled' || code === 'wall_timeout') {
+    return 'TOOL_TIMEOUT';
+  }
+  if (cancelReason != null || signal === 'SIGTERM' || signal === 'SIGKILL' || code === 'cancelled') {
+    return 'USER_CANCELLED';
+  }
+  if (code === 'ENOSPC') return 'DISK_FULL';
+  if (code === 'EACCES' || code === 'EPERM') return 'PERMISSION_DENIED';
+  if (typeof exitCode === 'number' && exitCode !== 0) return 'HOST_BLIND';
+  return 'HOST_BLIND';
+}
+
+/** Only registry-known codes may reach payload.error_code/reason_code. */
+export function registryCode(code) {
+  return isNonEmptyString(code) && REASON_CODES[code] ? code : 'HOST_BLIND';
+}
+
+/**
+ * DF-FR08 typed resource provenance (routeAdapter parity):
+ *   - caller-typed {value, source} with a real source → kept verbatim;
+ *   - numeric value without a trustworthy source → ESTIMATED (a number
+ *     exists, so UNKNOWN would be a lie; PROVIDER would claim an
+ *     unobserved measurement);
+ *   - no value → {value:null, source:'UNKNOWN'} — host-blind stays
+ *     explicitly unknown, never 0.
+ * Returns { resource, complete } — complete=false marks the record as
+ * telemetry-blind for summarizeTrace.
+ */
+export function typedResource(resource) {
+  const value = resource && typeof resource.value === 'number' && Number.isFinite(resource.value)
+    ? resource.value
+    : null;
+  const source = resource && RESOURCE_SOURCES.includes(resource.source)
+    ? resource.source
+    : null;
+  if (value === null) return { resource: { value: null, source: 'UNKNOWN' }, complete: false };
+  if (source && source !== 'UNKNOWN') return { resource: { value, source }, complete: true };
+  return { resource: { value, source: 'ESTIMATED' }, complete: true };
+}

package/src/core/memory/memoryEmit.js

@@ -0,0 +1,131 @@
+// memoryEmit.js (TASK-007, SPEC §5 DF2-FR08) — the single telemetry seam for
+// memory/retrieval call sites. Every record here is metadata-only: counts,
+// kind buckets, opaque sha256 refs, durations. Record text, query text,
+// paths and ids never enter a payload — the allowlist is the backstop, this
+// module is the discipline.
+//
+// Contract: O(1) hot path and never-throw. resolveStage(config) !== 'off'
+// short-circuits BEFORE any hashing/payload work so an off stage costs one
+// property walk; emit() itself already never throws and the wrapper swallows
+// anyway (a telemetry fault can never break the write/read path).
+
+import crypto from 'node:crypto';
+
+import { getRecorder } from '../observability/emit/lifecycle.js';
+import { resolveStage } from '../observability/emit/config.js';
+
+const REFS_MAX = 32;
+
+function sha256(text) {
+  return crypto.createHash('sha256').update(String(text)).digest('hex');
+}
+
+function kindBuckets(records) {
+  const kinds = {};
+  for (const record of records) {
+    const kind = typeof record?.type === 'string' ? record.type : 'unknown';
+    kinds[kind] = (kinds[kind] ?? 0) + 1;
+  }
+  return kinds;
+}
+
+function safeEmit(recorder, record) {
+  try {
+    recorder.emit(record);
+  } catch {
+    // Never-throw: a recorder fault must not break the memory path.
+  }
+}
+
+/**
+ * emitMemoryWrite({projectRoot, config, op, subject, recordCount, tombstoneCount})
+ * One `memory.write` record per persisted doc write. `subject` is the
+ * record(s) this write materially changed (or a raw id string) — hashed into
+ * opaque refs; `recordCount`/`tombstoneCount` describe the persisted doc.
+ */
+export function emitMemoryWrite({
+  projectRoot,
+  config,
+  op,
+  subject,
+  recordCount,
+  tombstoneCount,
+} = {}) {
+  if (resolveStage(config) === 'off') return;
+  const recorder = getRecorder({ projectRoot, config });
+  const list = (Array.isArray(subject) ? subject : subject == null ? [] : [subject])
+    .slice(0, REFS_MAX);
+  const refs = [];
+  for (const entry of list) {
+    const id = typeof entry === 'string' ? entry : entry?.id;
+    if (typeof id === 'string' && id.length > 0) refs.push(sha256(id));
+  }
+  safeEmit(recorder, {
+    semantic_name: 'memory.write',
+    payload: {
+      op: typeof op === 'string' ? op : 'write',
+      record_count: Number.isInteger(recordCount) ? recordCount : 0,
+      changed_count: refs.length,
+      kinds: kindBuckets(list.filter((e) => e != null && typeof e === 'object')),
+      record_refs: refs,
+      tombstone_count: Number.isInteger(tombstoneCount) ? tombstoneCount : 0,
+    },
+  });
+}
+
+/**
+ * emitRetrievalQuery({projectRoot, config, lane, scope, indexed,
+ *   candidateCount, returnedCount, durationMs, freshness})
+ * One `retrieval.query` record per search() call — lanes 'v2'|'legacy',
+ * never the query text.
+ */
+export function emitRetrievalQuery({
+  projectRoot,
+  config,
+  lane,
+  scope,
+  indexed,
+  candidateCount,
+  returnedCount,
+  durationMs,
+  freshness,
+} = {}) {
+  if (resolveStage(config) === 'off') return;
+  const recorder = getRecorder({ projectRoot, config });
+  const buckets = freshness && typeof freshness === 'object' ? freshness : {};
+  safeEmit(recorder, {
+    semantic_name: 'retrieval.query',
+    payload: {
+      lane: lane === 'legacy' ? 'legacy' : 'v2',
+      scope: typeof scope === 'string' ? scope : 'all',
+      indexed: indexed === true,
+      candidate_count: Number.isInteger(candidateCount) ? candidateCount : 0,
+      returned_count: Number.isInteger(returnedCount) ? returnedCount : 0,
+      duration_ms: Number.isFinite(durationMs) && durationMs >= 0 ? durationMs : 0,
+      freshness: buckets,
+    },
+  });
+}
+
+/**
+ * emitMemoryRetrieved({projectRoot, config, hits}) — one `memory.retrieved`
+ * record per returned hit: kind + opaque ref only.
+ */
+export function emitMemoryRetrieved({ projectRoot, config, hits } = {}) {
+  if (!Array.isArray(hits) || hits.length === 0) return;
+  if (resolveStage(config) === 'off') return;
+  const recorder = getRecorder({ projectRoot, config });
+  for (const hit of hits) {
+    const id = hit?.id;
+    if (typeof id !== 'string' || id.length === 0) continue;
+    safeEmit(recorder, {
+      semantic_name: 'memory.retrieved',
+      payload: {
+        kind: typeof hit.type === 'string' ? hit.type
+          : typeof hit.source === 'string' ? hit.source
+            : 'unknown',
+        record_ref: sha256(id),
+      },
+    });
+  }
+}

package/src/core/memory/memoryHit.js

@@ -111,7 +111,7 @@ export function rankHits(records, {
     if (!eligible(record, ctx, policy).ok) continue;
     if (!matchesRequestedScope(record, scope)) continue;
 
-    const lexical = scoreRecordTokens(record, queryTokens);
+    const lexical = scoreRecordTokens(record, queryTokens, nowMs);
     const typeWeight = RECORD_TYPE_WEIGHTS[record.type] ?? 1;
     const typeBonus = typeWeight / TYPE_WEIGHT_SCALE;
     const evidenceBonus = hasLocatorEvidence(record) ? 1 : 0;