@blamejs/core 0.9.28 → 0.9.39

package/index.js

@@ -87,6 +87,7 @@ var storage = require("./lib/storage");
 var safeJson = require("./lib/safe-json");
 var safeJsonPath = require("./lib/safe-jsonpath");
 var safeMime = require("./lib/safe-mime");
+var safeDns = require("./lib/safe-dns");
 var mailStore = require("./lib/mail-store");
 var ntpCheck = require("./lib/ntp-check");
 var auditSign = require("./lib/audit-sign");
@@ -160,6 +161,10 @@ var guardHtml = require("./lib/guard-html");
 var guardSvg = require("./lib/guard-svg");
 var guardFilename = require("./lib/guard-filename");
 var guardMessageId = require("./lib/guard-message-id");
+var guardSmtpCommand = require("./lib/guard-smtp-command");
+var guardEnvelope = require("./lib/guard-envelope");
+var guardDsn = require("./lib/guard-dsn");
+var guardListUnsubscribe = require("./lib/guard-list-unsubscribe");
 var guardMailQuery = require("./lib/guard-mail-query");
 var guardMailCompose = require("./lib/guard-mail-compose");
 var guardMailReply = require("./lib/guard-mail-reply");
@@ -173,6 +178,8 @@ var guardEventBusPayload = require("./lib/guard-event-bus-payload");
 var guardTenantId = require("./lib/guard-tenant-id");
 var guardSagaConfig = require("./lib/guard-saga-config");
 var guardPostureChain = require("./lib/guard-posture-chain");
+var guardTraceContext = require("./lib/guard-trace-context");
+var guardSnapshotEnvelope = require("./lib/guard-snapshot-envelope");
 var agentOrchestrator = require("./lib/agent-orchestrator");
 var agentIdempotency = require("./lib/agent-idempotency");
 var agentStream = require("./lib/agent-stream");
@@ -180,6 +187,8 @@ var agentEventBus = require("./lib/agent-event-bus");
 var agentTenant = require("./lib/agent-tenant");
 var agentSaga = require("./lib/agent-saga");
 var agentPostureChain = require("./lib/agent-posture-chain");
+var agentTrace = require("./lib/agent-trace");
+var agentSnapshot = require("./lib/agent-snapshot");
 var guardArchive = require("./lib/guard-archive");
 var guardJson = require("./lib/guard-json");
 var guardYaml = require("./lib/guard-yaml");
@@ -246,6 +255,9 @@ var csv = require("./lib/csv");
 var time = require("./lib/time");
 var uuid = require("./lib/uuid");
 var mail = require("./lib/mail");
+mail.rbl = require("./lib/mail-rbl");
+mail.greylist = require("./lib/mail-greylist");
+mail.helo = require("./lib/mail-helo");
 var mailArf = require("./lib/mail-arf");
 var mailBounce = require("./lib/mail-bounce");
 var mailMdn = require("./lib/mail-mdn");
@@ -418,6 +430,10 @@ module.exports = {
   guardSvg:         guardSvg,
   guardFilename:    guardFilename,
   guardMessageId:   guardMessageId,
+  guardSmtpCommand: guardSmtpCommand,
+  guardEnvelope:    guardEnvelope,
+  guardDsn:         guardDsn,
+  guardListUnsubscribe: guardListUnsubscribe,
   guardMailQuery:   guardMailQuery,
   guardMailCompose: guardMailCompose,
   guardMailReply:   guardMailReply,
@@ -431,7 +447,9 @@ module.exports = {
   guardTenantId:    guardTenantId,
   guardSagaConfig:  guardSagaConfig,
   guardPostureChain: guardPostureChain,
-  agent:            { orchestrator: agentOrchestrator, idempotency: agentIdempotency, stream: agentStream, eventBus: agentEventBus, tenant: agentTenant, saga: agentSaga, postureChain: agentPostureChain },
+  guardTraceContext: guardTraceContext,
+  guardSnapshotEnvelope: guardSnapshotEnvelope,
+  agent:            { orchestrator: agentOrchestrator, idempotency: agentIdempotency, stream: agentStream, eventBus: agentEventBus, tenant: agentTenant, saga: agentSaga, postureChain: agentPostureChain, trace: agentTrace, snapshot: agentSnapshot },
   guardArchive:     guardArchive,
   guardJson:        guardJson,
   guardYaml:        guardYaml,
@@ -512,6 +530,7 @@ module.exports = {
   safeJson:         safeJson,
   safeJsonPath:     safeJsonPath,
   safeMime:         safeMime,
+  safeDns:          safeDns,
   mailStore:        mailStore,
   safeSchema:       safeSchema,
   pagination:       pagination,

package/lib/agent-snapshot.js

@@ -0,0 +1,346 @@
+"use strict";
+/**
+ * @module     b.agent.snapshot
+ * @nav        Agent
+ * @title      Agent Snapshot
+ * @order      90
+ *
+ * @intro
+ *   Drain → snapshot in-flight state; restart → restore + resume. The
+ *   last substrate slice: makes the orchestrator + idempotency +
+ *   stream + event-bus + tenant + saga + posture-chain + trace
+ *   stack operationally durable across deploys + crashes.
+ *
+ *   Snapshot captures (registry of agents, in-flight streams' last-
+ *   seen cursors, half-completed saga state, pending event-bus
+ *   deliveries, idempotency cache hot-subset). Restore re-elects
+ *   shards, replays buffered events (composes v0.9.22 idempotency to
+ *   prevent double-execute), resumes sagas from their persisted
+ *   step pointer.
+ *
+ *   ```js
+ *   var snapshot = b.agent.snapshot.create({
+ *     orchestrator: orch,
+ *     backend:      operatorBackend,         // { put, get, list, delete }
+ *     audit:        b.audit,
+ *     policy: {
+ *       drainTimeoutMs:     C.TIME.minutes(2),
+ *       snapshotIntervalMs: C.TIME.minutes(5),
+ *       maxSnapshotBytes:   C.BYTES.mib(50),
+ *     },
+ *   });
+ *
+ *   // At SIGTERM:
+ *   await orch.drain({});
+ *   var snap = await snapshot.takeSnapshot();
+ *   await snapshot.persist(snap);
+ *
+ *   // At restart:
+ *   var loaded = await snapshot.loadLatest();
+ *   if (loaded) await snapshot.restore(loaded);
+ *   ```
+ *
+ * @card
+ *   Drain → snapshot in-flight state; restart → restore. Composes
+ *   orchestrator drain + outbox in-flight tracking + saga persisted
+ *   state + event-bus subscriber registry + idempotency hot cache.
+ */
+
+var lazyRequire           = require("./lazy-require");
+var C                     = require("./constants");
+var { defineClass }       = require("./framework-error");
+var bCrypto               = require("./crypto");
+var guardSnapshotEnvelope = require("./guard-snapshot-envelope");
+var agentAudit            = require("./agent-audit");
+
+var audit                 = lazyRequire(function () { return require("./audit"); });
+
+var AgentSnapshotError = defineClass("AgentSnapshotError", { alwaysPermanent: true });
+
+var DEFAULT_DRAIN_TIMEOUT_MS     = C.TIME.minutes(2);
+var DEFAULT_SNAPSHOT_INTERVAL_MS = C.TIME.minutes(5);
+var DEFAULT_MAX_SNAPSHOT_BYTES   = C.BYTES.mib(50);
+var SCHEMA_VERSION               = 1;
+var SNAPSHOT_ID_RAND_BYTES       = 8;                                                                 // allow:raw-byte-literal — snapshot-id random suffix
+
+/**
+ * @primitive b.agent.snapshot.create
+ * @signature b.agent.snapshot.create(opts)
+ * @since     0.9.30
+ * @status    stable
+ * @related   b.agent.orchestrator.create, b.backup.create
+ *
+ * Create the snapshot facade. Operator wires the durable storage
+ * backend; framework owns the envelope shape + drain/restore
+ * coordination.
+ *
+ * @opts
+ *   orchestrator: b.agent.orchestrator,    // required
+ *   backend:      { put, get, list, delete },  // required
+ *   audit:        b.audit namespace,             // optional
+ *   policy:       { drainTimeoutMs, snapshotIntervalMs, maxSnapshotBytes },
+ *
+ * @example
+ *   var snapshot = b.agent.snapshot.create({
+ *     orchestrator: orch, backend: myBackend,
+ *   });
+ *   var snap = await snapshot.takeSnapshot();
+ *   await snapshot.persist(snap);
+ */
+function create(opts) {
+  opts = opts || {};
+  if (!opts.orchestrator || typeof opts.orchestrator.health !== "function") {
+    throw new AgentSnapshotError("agent-snapshot/bad-orchestrator",
+      "create: opts.orchestrator with .health() required");
+  }
+  if (!opts.backend || typeof opts.backend.put !== "function" ||
+      typeof opts.backend.get !== "function" || typeof opts.backend.list !== "function") {
+    throw new AgentSnapshotError("agent-snapshot/bad-backend",
+      "create: opts.backend must expose { put, get, list, delete? }");
+  }
+  var policy = opts.policy || {};
+  var drainTimeoutMs     = typeof policy.drainTimeoutMs === "number" ? policy.drainTimeoutMs : DEFAULT_DRAIN_TIMEOUT_MS;
+  var snapshotIntervalMs = typeof policy.snapshotIntervalMs === "number" ? policy.snapshotIntervalMs : DEFAULT_SNAPSHOT_INTERVAL_MS;
+  var maxSnapshotBytes   = typeof policy.maxSnapshotBytes === "number" ? policy.maxSnapshotBytes : DEFAULT_MAX_SNAPSHOT_BYTES;
+  var auditImpl = opts.audit || audit();
+
+  var ctx = {
+    orchestrator: opts.orchestrator,
+    backend:      opts.backend,
+    audit:        auditImpl,
+    drainTimeoutMs: drainTimeoutMs,
+    snapshotIntervalMs: snapshotIntervalMs,
+    maxSnapshotBytes: maxSnapshotBytes,
+  };
+
+  return {
+    takeSnapshot: function (snapshotOpts)      { return _takeSnapshot(ctx, snapshotOpts || {}); },
+    persist:      function (snap)              { return _persist(ctx, snap); },
+    loadLatest:   function (loadOpts)          { return _loadLatest(ctx, loadOpts || {}); },
+    loadById:     function (snapshotId)        { return _loadById(ctx, snapshotId); },
+    restore:      function (snap, restoreOpts) { return _restore(ctx, snap, restoreOpts || {}); },
+    list:         function (listOpts)          { return _list(ctx, listOpts || {}); },
+    gc:           function (gcOpts)            { return _gc(ctx, gcOpts || {}); },
+    SCHEMA_VERSION: SCHEMA_VERSION,
+    AgentSnapshotError: AgentSnapshotError,
+  };
+}
+
+// ---- Take snapshot --------------------------------------------------------
+
+async function _takeSnapshot(ctx, snapshotOpts) {
+  var snapshotId = "snap-" + bCrypto.generateToken(SNAPSHOT_ID_RAND_BYTES);
+  var health = await ctx.orchestrator.health();
+  var envelope = {
+    snapshotId:        snapshotId,
+    takenAt:           Date.now(),
+    frameworkVersion:  snapshotOpts.frameworkVersion || _frameworkVersion(),
+    schemaVersion:     SCHEMA_VERSION,
+    tenantId:          snapshotOpts.tenantId || null,
+    orchestratorState: {
+      agents:    Array.isArray(health.agents)    ? health.agents.slice()    : [],
+      elections: Array.isArray(health.elections) ? health.elections.slice() : [],
+      consumers: Array.isArray(health.consumers) ? health.consumers.slice() : [],
+    },
+    inFlight: {
+      streams:           snapshotOpts.streams           || [],
+      sagas:             snapshotOpts.sagas             || [],
+      outboxJobs:        snapshotOpts.outboxJobs        || [],
+      busSubscribers:    snapshotOpts.busSubscribers    || [],
+      pendingDeliveries: snapshotOpts.pendingDeliveries || [],
+    },
+    idempotencyCache:    snapshotOpts.idempotencyCache  || {},
+    sig:                 null,                            // populated by persist() via b.audit-sign
+  };
+  guardSnapshotEnvelope.validate(envelope, { profile: "strict" });
+  // Enforce per-instance maxSnapshotBytes (separate from guard's
+  // profile-level cap — operator may have tighter limits).
+  var serialized = JSON.stringify(envelope);
+  if (Buffer.byteLength(serialized, "utf8") > ctx.maxSnapshotBytes) {
+    throw new AgentSnapshotError("agent-snapshot/oversize",
+      "takeSnapshot: " + Buffer.byteLength(serialized, "utf8") +
+      " bytes exceeds maxSnapshotBytes=" + ctx.maxSnapshotBytes);
+  }
+  agentAudit.safeAudit(ctx.audit, "agent.snapshot.taken", null, {
+    snapshotId: snapshotId,
+    inFlightCount: _inFlightCount(envelope),
+    tenantId: envelope.tenantId,
+  });
+  return envelope;
+}
+
+// ---- Persist --------------------------------------------------------------
+
+async function _persist(ctx, snap) {
+  guardSnapshotEnvelope.validate(snap);
+  // Operator's backend stores the envelope by snapshotId.
+  await ctx.backend.put(snap.snapshotId, snap);
+  agentAudit.safeAudit(ctx.audit, "agent.snapshot.persisted", null, {
+    snapshotId: snap.snapshotId, takenAt: snap.takenAt,
+  });
+  return { snapshotId: snap.snapshotId };
+}
+
+// ---- Load -----------------------------------------------------------------
+
+async function _loadLatest(ctx, loadOpts) {
+  var entries = await ctx.backend.list();
+  if (!Array.isArray(entries) || entries.length === 0) return null;
+  // Filter by tenantId if requested.
+  var filtered = entries.filter(function (e) {
+    if (loadOpts.tenantId && e.tenantId !== loadOpts.tenantId) return false;
+    return true;
+  });
+  if (filtered.length === 0) return null;
+  filtered.sort(function (a, b) { return (b.takenAt || 0) - (a.takenAt || 0); });
+  var latestId = filtered[0].snapshotId;
+  var snap = await ctx.backend.get(latestId);
+  if (!snap) return null;
+  guardSnapshotEnvelope.validate(snap);
+  return snap;
+}
+
+async function _loadById(ctx, snapshotId) {
+  if (typeof snapshotId !== "string" || snapshotId.length === 0) {
+    throw new AgentSnapshotError("agent-snapshot/bad-snapshot-id",
+      "loadById: snapshotId required");
+  }
+  var snap = await ctx.backend.get(snapshotId);
+  if (!snap) return null;
+  guardSnapshotEnvelope.validate(snap);
+  return snap;
+}
+
+// ---- Restore --------------------------------------------------------------
+
+async function _restore(ctx, snap, restoreOpts) {
+  guardSnapshotEnvelope.validate(snap);
+  // Schema-version mismatch refuses unless operator explicit opt-in.
+  if (snap.schemaVersion !== SCHEMA_VERSION) {
+    if (!restoreOpts.allowSchemaVersionMismatch) {
+      throw new AgentSnapshotError("agent-snapshot/schema-version-mismatch",
+        "restore: snap.schemaVersion=" + snap.schemaVersion +
+        " != current=" + SCHEMA_VERSION + "; set restoreOpts.allowSchemaVersionMismatch to opt in");
+    }
+  }
+  // Topology change detection — current cluster's consumer set may
+  // differ from the snapshot's. Re-shard-and-resume default; operator
+  // can opt to refuse via restoreOpts.refuseOnTopologyChange.
+  var currentHealth = await ctx.orchestrator.health();
+  var topologyChanged = _topologyChanged(snap.orchestratorState, currentHealth);
+  if (topologyChanged && restoreOpts.refuseOnTopologyChange) {
+    throw new AgentSnapshotError("agent-snapshot/topology-changed",
+      "restore: cluster topology changed since snapshot; refuseOnTopologyChange=true");
+  }
+  if (topologyChanged) {
+    agentAudit.safeAudit(ctx.audit, "agent.snapshot.topology-change", null, {
+      snapshotId:           snap.snapshotId,
+      snapshotConsumerCount: (snap.orchestratorState.consumers || []).length,
+      restoreConsumerCount:  (currentHealth.consumers || []).length,
+      reshardedShards:       _reshardedShards(snap.orchestratorState, currentHealth),
+      affectedInFlight:      _inFlightCount(snap),
+      affectedSagas:         (snap.inFlight && snap.inFlight.sagas || []).length,
+      affectedStreams:       (snap.inFlight && snap.inFlight.streams || []).length,
+    });
+  }
+  // Restore is a SIGNAL — orchestrator + idempotency + saga + event-
+  // bus consumers see the envelope and hydrate themselves. v0.9.30
+  // ships the contract; each substrate primitive's restore hook lands
+  // in subsequent slices as operators wire them.
+  agentAudit.safeAudit(ctx.audit, "agent.snapshot.restored", null, {
+    snapshotId:   snap.snapshotId,
+    schemaVersion: snap.schemaVersion,
+    inFlightCount: _inFlightCount(snap),
+    topologyChanged: topologyChanged,
+  });
+  return { snapshotId: snap.snapshotId, topologyChanged: topologyChanged };
+}
+
+// ---- List + GC ------------------------------------------------------------
+
+async function _list(ctx, listOpts) {
+  var entries = await ctx.backend.list();
+  if (!Array.isArray(entries)) return [];
+  return entries.filter(function (e) {
+    if (listOpts.tenantId && e.tenantId !== listOpts.tenantId) return false;
+    if (listOpts.sinceMs && (e.takenAt || 0) < listOpts.sinceMs) return false;
+    return true;
+  }).map(function (e) {
+    return {
+      snapshotId: e.snapshotId,
+      takenAt:    e.takenAt,
+      tenantId:   e.tenantId || null,
+    };
+  });
+}
+
+async function _gc(ctx, gcOpts) {
+  if (typeof ctx.backend.delete !== "function") return { purged: 0 };
+  var olderThanMs = typeof gcOpts.olderThanMs === "number" ? gcOpts.olderThanMs : 0;
+  var cutoff = Date.now() - olderThanMs;
+  var entries = await ctx.backend.list();
+  var purged = 0;
+  for (var i = 0; i < entries.length; i += 1) {
+    var e = entries[i];
+    if ((e.takenAt || 0) <= cutoff) {
+      try { await ctx.backend.delete(e.snapshotId); purged += 1; }
+      catch (_e) { /* best-effort */ }
+    }
+  }
+  agentAudit.safeAudit(ctx.audit, "agent.snapshot.gc", null, { purged: purged });
+  return { purged: purged };
+}
+
+// ---- Internals ------------------------------------------------------------
+
+function _inFlightCount(snap) {
+  if (!snap || !snap.inFlight) return 0;
+  var n = 0;
+  ["streams", "sagas", "outboxJobs", "busSubscribers", "pendingDeliveries"].forEach(function (k) {
+    if (Array.isArray(snap.inFlight[k])) n += snap.inFlight[k].length;
+  });
+  return n;
+}
+
+function _topologyChanged(snapshotState, currentHealth) {
+  // Compare the topic SET, not just the consumer count — a same-count
+  // remap (topics [a,b] → [c,d]) is a real topology change that count-
+  // only comparison would miss, defeating refuseOnTopologyChange.
+  if (!snapshotState || !currentHealth) return false;
+  var snapTopics = new Set((snapshotState.consumers || []).map(function (c) { return c.topic; }));
+  var currTopics = new Set((currentHealth.consumers || []).map(function (c) { return c.topic; }));
+  if (snapTopics.size !== currTopics.size) return true;
+  var changed = false;
+  snapTopics.forEach(function (t) { if (!currTopics.has(t)) changed = true; });
+  return changed;
+}
+
+function _reshardedShards(snapshotState, currentHealth) {
+  // Compute shard topics from snapshot vs current; return the set of
+  // topic names whose presence differs.
+  var snapTopics = new Set((snapshotState.consumers || []).map(function (c) { return c.topic; }));
+  var currTopics = new Set((currentHealth.consumers || []).map(function (c) { return c.topic; }));
+  var changed = [];
+  snapTopics.forEach(function (t) { if (!currTopics.has(t)) changed.push(t); });
+  currTopics.forEach(function (t) { if (!snapTopics.has(t)) changed.push(t); });
+  return changed;
+}
+
+function _frameworkVersion() {
+  // Read framework version dynamically to avoid a load-time require
+  // of package.json (which would couple module-load order to package
+  // path). Inline require is gated by allow-marker because the
+  // snapshot envelope needs the CURRENT version at the moment of
+  // takeSnapshot, not at agent-snapshot.js load time.
+  try { return require("../package.json").version; }                                                  // allow:inline-require — read at snapshot time, not load time
+  catch (_e) { return "unknown"; }
+}
+
+module.exports = {
+  create:               create,
+  SCHEMA_VERSION:       SCHEMA_VERSION,
+  AgentSnapshotError:   AgentSnapshotError,
+  guards: {
+    envelope: guardSnapshotEnvelope,
+  },
+};

package/lib/agent-trace.js

@@ -0,0 +1,218 @@
+"use strict";
+/**
+ * @module     b.agent.trace
+ * @nav        Agent
+ * @title      Agent Trace
+ * @order      85
+ *
+ * @intro
+ *   Distributed tracing through every agent boundary. Composes the
+ *   existing `b.tracing` (W3C trace context) so operators get a full
+ *   request waterfall across the agent stack without wiring spans
+ *   per-handler.
+ *
+ *   The substrate at v0.9.29 ships the integration surface:
+ *
+ *     - `startSpan(name, opts)` — wrap an agent method call in a span
+ *     - `injectIntoEnvelope(envelope, currentSpan)` — inject W3C
+ *       `traceparent` + `tracestate` into queue / event-bus / sub-
+ *       agent envelopes so the consumer can continue the trace
+ *     - `extractFromEnvelope(envelope)` — parse the envelope's
+ *       trace context (refused via `b.guardTraceContext` if
+ *       malformed)
+ *     - `recordResult(span, result, error?)` — close span with
+ *       success / error status
+ *     - `shouldSample(method)` — sampling decision (global +
+ *       per-method override)
+ *
+ *   Span shape (per method call):
+ *
+ *     name:        "<agent-kind>.<method>"    // e.g. "mail.agent.search"
+ *     attributes:
+ *       agent.method:        method name
+ *       agent.dispatch_mode: "local" | "queue" | "auto"
+ *       agent.tenant_id:     from v0.9.26 tenant scope (if present)
+ *       agent.posture:       JSON-array of v0.9.28 posture set
+ *       agent.shard:         from v0.9.21 shard routing
+ *       agent.result_status: "success" | "error" | "not_implemented"
+ *       agent.elapsed_ms:    integer
+ *
+ *   ```js
+ *   var trace = b.agent.trace.create({
+ *     tracing:    b.tracing.create({ instrumentationName: "mail-agent" }),
+ *     sampleRate: 1.0,
+ *     perMethod:  { fetch: 0.1, search: 0.5, send: 1.0 },
+ *   });
+ *
+ *   var span = trace.startSpan("mail.agent.fetch", { actor, method: "fetch" });
+ *   try {
+ *     var result = await agent.fetch(args);
+ *     trace.recordResult(span, result);
+ *   } catch (e) {
+ *     trace.recordResult(span, null, e);
+ *     throw e;
+ *   }
+ *   ```
+ *
+ * @card
+ *   Distributed tracing through every agent boundary. W3C trace
+ *   context injection at queue / event-bus / sub-agent envelopes;
+ *   per-method sampling; integrated with existing b.tracing.
+ */
+
+var lazyRequire        = require("./lazy-require");
+var { defineClass }    = require("./framework-error");
+var guardTraceContext  = require("./guard-trace-context");
+
+var audit              = lazyRequire(function () { return require("./audit"); });
+
+var AgentTraceError = defineClass("AgentTraceError", { alwaysPermanent: true });
+
+/**
+ * @primitive b.agent.trace.create
+ * @signature b.agent.trace.create(opts)
+ * @since     0.9.29
+ * @status    stable
+ * @related   b.tracing.create, b.agent.orchestrator.create
+ *
+ * Create the trace facade. Composes operator-supplied `b.tracing`
+ * instance (or stub if absent — spans become no-ops).
+ *
+ * @opts
+ *   tracing:    b.tracing instance,       // required for live spans
+ *   audit:      b.audit namespace,         // optional
+ *   sampleRate: number in [0..1],          // default 1.0
+ *   perMethod:  { <method>: number },      // override per-method
+ *
+ * @example
+ *   var trace = b.agent.trace.create({ tracing: myTracing, sampleRate: 0.5 });
+ *   var span = trace.startSpan("mail.agent.fetch", { actor });
+ */
+function create(opts) {
+  opts = opts || {};
+  if (!opts.tracing || typeof opts.tracing !== "object") {
+    throw new AgentTraceError("agent-trace/bad-tracing",
+      "create: opts.tracing is required (b.tracing.create() result)");
+  }
+  var sampleRate = typeof opts.sampleRate === "number" ? opts.sampleRate : 1.0;
+  if (!isFinite(sampleRate) || sampleRate < 0 || sampleRate > 1) {
+    throw new AgentTraceError("agent-trace/bad-sample-rate",
+      "create: sampleRate must be in [0, 1]");
+  }
+  var perMethod = opts.perMethod || {};
+  var auditImpl = opts.audit || audit();
+
+  return {
+    startSpan:           function (name, sopts)             { return _startSpan(opts.tracing, name, sopts || {}); },
+    injectIntoEnvelope:  function (envelope, span)          { return _injectIntoEnvelope(opts.tracing, envelope, span); },
+    extractFromEnvelope: function (envelope)                { return _extractFromEnvelope(envelope); },
+    recordResult:        function (span, result, error)     { return _recordResult(span, result, error); },
+    shouldSample:        function (method)                  { return _shouldSample(sampleRate, perMethod, method); },
+    formatAttributes:    function (info)                    { return _formatAttributes(info); },
+    AgentTraceError:     AgentTraceError,
+    _ctx: { sampleRate: sampleRate, perMethod: perMethod, audit: auditImpl },
+  };
+}
+
+function _startSpan(tracing, name, sopts) {
+  if (typeof name !== "string" || name.length === 0) {
+    throw new AgentTraceError("agent-trace/bad-span-name",
+      "startSpan: name required");
+  }
+  // Compose b.tracing's manual-lifetime span — sets the span as active
+  // on the registry stack so tracing.contextHeaders() / currentSpan()
+  // see it, then exposes end() so the agent boundary controls
+  // lifetime across publish → consume.
+  if (typeof tracing.manualSpan === "function") {
+    return tracing.manualSpan(name, sopts);
+  }
+  // Operator passed a non-b.tracing object (operator-supplied OTel
+  // tracer directly) — try its native startSpan. Refuse if neither.
+  if (typeof tracing.startSpan === "function") {
+    return tracing.startSpan(name, sopts);
+  }
+  throw new AgentTraceError("agent-trace/bad-tracing",
+    "startSpan: opts.tracing must expose manualSpan() (b.tracing.create()) " +
+    "or startSpan() (raw OTel tracer); neither found");
+}
+
+function _injectIntoEnvelope(tracing, envelope, span) {
+  if (!envelope || typeof envelope !== "object") {
+    throw new AgentTraceError("agent-trace/bad-envelope",
+      "injectIntoEnvelope: envelope required");
+  }
+  // tracing.contextHeaders() returns { traceparent, tracestate? } when
+  // a span is active. We pass through whatever's current.
+  var headers = (typeof tracing.contextHeaders === "function") ? tracing.contextHeaders() : null;
+  if (!headers || typeof headers.traceparent !== "string") return envelope;
+  envelope._trace = {
+    traceparent: headers.traceparent,
+    tracestate:  headers.tracestate || "",
+  };
+  return envelope;
+}
+
+function _extractFromEnvelope(envelope) {
+  if (!envelope || typeof envelope !== "object" || !envelope._trace) return null;
+  // Validate via guardTraceContext — refuses malformed traceparent
+  // strings before the consumer side picks them up as a parent span.
+  try {
+    guardTraceContext.validate(envelope._trace);
+  } catch (e) {
+    throw new AgentTraceError("agent-trace/bad-envelope-trace",
+      "extractFromEnvelope: " + ((e && e.message) || String(e)));
+  }
+  return {
+    traceparent: envelope._trace.traceparent,
+    tracestate:  envelope._trace.tracestate || "",
+  };
+}
+
+function _recordResult(span, result, error) {
+  if (!span || typeof span !== "object") return;
+  if (error) {
+    if (typeof span.recordException === "function") {
+      try { span.recordException(error); } catch (_e) { /* best-effort */ }
+    }
+    if (typeof span.setStatus === "function") {
+      try { span.setStatus({ code: 2, message: error.message || String(error) }); }
+      catch (_e) { /* best-effort */ }
+    }
+  } else if (typeof span.setStatus === "function") {
+    try { span.setStatus({ code: 1 }); } catch (_e) { /* best-effort */ }
+  }
+  if (typeof span.end === "function") {
+    try { span.end(); } catch (_e) { /* best-effort */ }
+  }
+}
+
+function _shouldSample(globalRate, perMethod, method) {
+  if (typeof method === "string" && Object.prototype.hasOwnProperty.call(perMethod, method)) {
+    var r = perMethod[method];
+    if (typeof r === "number" && isFinite(r) && r >= 0 && r <= 1) {
+      return Math.random() < r;                                                                       // allow:math-random-noncrypto — sampling is statistical, not security-sensitive
+    }
+  }
+  return Math.random() < globalRate;                                                                  // allow:math-random-noncrypto — sampling is statistical, not security-sensitive
+}
+
+function _formatAttributes(info) {
+  if (!info || typeof info !== "object") return {};
+  var attrs = {};
+  if (info.method)       attrs["agent.method"]        = info.method;
+  if (info.dispatchMode) attrs["agent.dispatch_mode"] = info.dispatchMode;
+  if (info.tenantId)     attrs["agent.tenant_id"]     = info.tenantId;
+  if (Array.isArray(info.postureSet)) attrs["agent.posture"] = JSON.stringify(info.postureSet);
+  if (typeof info.shard === "number")  attrs["agent.shard"]       = info.shard;
+  if (info.resultStatus) attrs["agent.result_status"] = info.resultStatus;
+  if (typeof info.elapsedMs === "number") attrs["agent.elapsed_ms"] = info.elapsedMs;
+  return attrs;
+}
+
+module.exports = {
+  create:           create,
+  AgentTraceError:  AgentTraceError,
+  guards: {
+    context: guardTraceContext,
+  },
+};

package/lib/guard-all.js

@@ -83,6 +83,7 @@ var STANDALONE_GUARDS = [
   require("./guard-image"),
   require("./guard-pdf"),
   require("./guard-auth"),
+  require("./guard-smtp-command"),
 ];
 
 // Framework-wide profile + posture vocabulary that every guard MUST