@blamejs/blamejs-shop 0.0.44

package/lib/vendor/blamejs/lib/agent-trace.js

@@ -0,0 +1,281 @@
+"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 agentAudit         = require("./agent-audit");
+
+var audit              = lazyRequire(function () { return require("./audit"); });
+
+var AgentTraceError = defineClass("AgentTraceError", { alwaysPermanent: true });
+
+// SUBSTRATE-24 — once-per-process audit emit on the first tracer
+// failure each install fires. Operators get the signal even when
+// individual span calls are best-effort suppressed.
+var _failureAuditEmittedFor = Object.create(null);
+function _emitFirstFailureAudit(auditImpl, kind, message) {
+  if (_failureAuditEmittedFor[kind]) return;
+  _failureAuditEmittedFor[kind] = true;
+  agentAudit.safeAudit(auditImpl, "agent.trace.tracer_failure", null, {
+    kind: kind, message: message ? String(message).slice(0, 256) : "",                                  // allow:raw-byte-literal — audit-message char cap
+    rateLimited: "first-occurrence-only",
+  });
+}
+
+/**
+ * @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 || {}, auditImpl); },
+    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, auditImpl); },
+    // SUBSTRATE-17 — `shouldSample` now takes a traceId so the same
+    // trace gets the same decision across hops. Operator-supplied
+    // traceId comes from the W3C `traceparent` header at request-
+    // entry; absent that, falls back to Math.random (start of trace).
+    shouldSample:        function (method, traceId)         { return _shouldSample(sampleRate, perMethod, method, traceId); },
+    formatAttributes:    function (info)                    { return _formatAttributes(info); },
+    AgentTraceError:     AgentTraceError,
+    _ctx: { sampleRate: sampleRate, perMethod: perMethod, audit: auditImpl },
+  };
+}
+
+function _startSpan(tracing, name, sopts, auditImpl) {
+  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.
+  try {
+    if (typeof tracing.manualSpan === "function") {
+      return tracing.manualSpan(name, sopts);
+    }
+    if (typeof tracing.startSpan === "function") {
+      return tracing.startSpan(name, sopts);
+    }
+  } catch (e) {
+    // SUBSTRATE-24 — tracer failures should not crash the agent's
+    // method call; surface the first failure to the audit chain
+    // (rate-limited) so operators get the signal.
+    _emitFirstFailureAudit(auditImpl, "startSpan", e && e.message);
+    return _noopSpan();
+  }
+  throw new AgentTraceError("agent-trace/bad-tracing",
+    "startSpan: opts.tracing must expose manualSpan() (b.tracing.create()) " +
+    "or startSpan() (raw OTel tracer); neither found");
+}
+
+function _noopSpan() {
+  // Returned when the tracer threw — caller can still call
+  // recordException / setStatus / end without further errors.
+  return {
+    end:             function () {},
+    setStatus:       function () {},
+    recordException: function () {},
+    isNoop:          true,
+  };
+}
+
+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, auditImpl) {
+  if (!span || typeof span !== "object") return;
+  // SUBSTRATE-24 — surface first occurrence of each span-op failure
+  // via audit so the operator gets the signal. Subsequent failures
+  // stay silent (best-effort) per the operational spec.
+  if (error) {
+    if (typeof span.recordException === "function") {
+      try { span.recordException(error); }
+      catch (e) { _emitFirstFailureAudit(auditImpl, "recordException", e && e.message); }
+    }
+    if (typeof span.setStatus === "function") {
+      try { span.setStatus({ code: 2, message: error.message || String(error) }); }
+      catch (e) { _emitFirstFailureAudit(auditImpl, "setStatus", e && e.message); }
+    }
+  } else if (typeof span.setStatus === "function") {
+    try { span.setStatus({ code: 1 }); }
+    catch (e) { _emitFirstFailureAudit(auditImpl, "setStatus", e && e.message); }
+  }
+  if (typeof span.end === "function") {
+    try { span.end(); }
+    catch (e) { _emitFirstFailureAudit(auditImpl, "end", e && e.message); }
+  }
+}
+
+// SUBSTRATE-17 — deterministic sampling per W3C Trace Context §3.2.3.1.
+// `Math.random` makes child-vs-parent sampling decisions non-coherent:
+// a parent span sampled OUT can still have child spans sampled IN,
+// producing orphaned spans operators can't correlate. Hashing the
+// 16-byte trace-id deterministically routes every span in a trace to
+// the same decision. When traceId is absent (start of a trace at
+// request-entry boundary) we still use Math.random as the seeding
+// roll; downstream callers pass the resulting traceId so children
+// inherit the decision.
+function _shouldSample(globalRate, perMethod, method, traceId) {
+  var rate = globalRate;
+  if (typeof method === "string" && Object.prototype.hasOwnProperty.call(perMethod, method)) {
+    var r = perMethod[method];
+    if (typeof r === "number" && isFinite(r) && r >= 0 && r <= 1) rate = r;
+  }
+  if (rate <= 0) return false;
+  if (rate >= 1) return true;
+  if (typeof traceId === "string" && /^[0-9a-fA-F]{32}$/.test(traceId)) {
+    // Use the low 32 bits of the trace-id as the sampling roll
+    // (W3C-compatible). Hash modulo 1e9 → divide by 1e9 puts the
+    // result in [0,1) deterministically.
+    var lo = parseInt(traceId.slice(-8), 16);                                                          // allow:raw-byte-literal — low 32 bits of trace-id hex
+    var roll = (lo >>> 0) / 0x100000000;                                                                // allow:raw-byte-literal — 2^32 normalization divisor
+    return roll < rate;
+  }
+  // No trace-id supplied — start of a new trace. Operators wire
+  // shouldSample(method, ctx.traceId) on every downstream hop so
+  // children inherit the decision deterministically.
+  return Math.random() < rate;                                                                          // allow:math-random-noncrypto — start-of-trace seed only; downstream hops pass traceId for deterministic propagation
+}
+
+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,
+  },
+  _resetForTest:    function () { _failureAuditEmittedFor = Object.create(null); },
+};

package/lib/vendor/blamejs/lib/ai-adverse-decision.js

@@ -0,0 +1,184 @@
+"use strict";
+/**
+ * b.ai.adverseDecision — adverse-decision wrapper for automated
+ * decisions affecting consumer rights.
+ *
+ * GDPR Article 22, EU AI Act Article 86, Colorado AI Act, NYC Local
+ * Law 144, and Equal Credit Opportunity Act §1002.9 all require some
+ * form of consumer notice + explanation when an automated decision
+ * adversely affects a person (denial of credit, denial of employment,
+ * adverse insurance pricing, etc.).
+ *
+ * The primitive wraps an operator-supplied predicate and:
+ *   - logs every decision with audit-chain attribution
+ *   - emits a structured consumer-rights notice on adverse outcomes
+ *   - pulls operator-supplied principal reasons (the "specific reasons
+ *     for the action" that ECOA + similar regimes require)
+ *
+ *   var hireDecision = b.ai.adverseDecision.wrap({
+ *     name:         "hire-screening",
+ *     model:        "screening-v3.1",
+ *     legalBasis:   "ecoa-1002.9",
+ *     decide:       function (applicant) {
+ *       var score = scoreModel(applicant);
+ *       return {
+ *         outcome:        score < 0.5 ? "adverse" : "favorable",
+ *         score:          score,
+ *         principalReasons: score < 0.5 ? ["insufficient-credit-history", "..."] : [],
+ *       };
+ *     },
+ *     onAdverse:    async function (subject, decision) {
+ *       await mailer.send({ to: subject.email, ... });
+ *     },
+ *   });
+ *
+ *   var decision = await hireDecision({ id: "applicant-1234", email: "..." });
+ *   // decision = { outcome, score, principalReasons, adverseNotice? }
+ *
+ * adverseNotice (when outcome === "adverse"):
+ *   {
+ *     subjectId:     "applicant-1234",
+ *     decisionAt:    1715040000000,
+ *     model:         "screening-v3.1",
+ *     legalBasis:    "ecoa-1002.9",
+ *     principalReasons: [...],
+ *     consumerRights: {
+ *       requestExplanation: true,
+ *       requestHumanReview: true,
+ *       requestAppeal:      true,
+ *       requestData:        true,
+ *       statutoryDeadlines: { explanation: "30d", appeal: "60d" }
+ *     }
+ *   }
+ */
+
+var defineClass = require("./framework-error").defineClass;
+var lazyRequire = require("./lazy-require");
+var validateOpts = require("./validate-opts");
+
+var audit = lazyRequire(function () { return require("./audit"); });
+var observability = lazyRequire(function () { return require("./observability"); });
+
+var AdverseDecisionError = defineClass("AdverseDecisionError", { alwaysPermanent: true });
+
+// Per-regime statutory deadlines for the consumer-rights surfaces.
+// Operators select via opts.legalBasis; the framework attaches the
+// right deadline shape to each adverseNotice.
+var REGIME_DEADLINES = Object.freeze({
+  "gdpr-22":           { explanation: "30d", humanReview: "30d", appeal: "30d", regulation: "GDPR Article 22" },
+  "ai-act-86":         { explanation: "30d", humanReview: "30d", appeal: "30d", regulation: "EU AI Act Article 86" },
+  "ecoa-1002.9":       { explanation: "30d", humanReview: null, appeal: null,   regulation: "ECOA 12 CFR §1002.9" },
+  "colorado-ai-act":   { explanation: "60d", humanReview: "60d", appeal: "60d", regulation: "Colorado AI Act" },
+  "nyc-ll-144":        { explanation: "10d", humanReview: null, appeal: null,   regulation: "NYC Local Law 144" },
+  "fcra-615":          { explanation: "60d", humanReview: null, appeal: null,   regulation: "FCRA 15 USC §1681m" },
+  "operator-defined":  { explanation: null,  humanReview: null, appeal: null,   regulation: "operator-supplied" },
+});
+
+function wrap(opts) {
+  opts = opts || {};
+  validateOpts(opts, [
+    "name", "model", "legalBasis", "decide", "onAdverse",
+    "audit", "now",
+  ], "ai.adverseDecision");
+
+  validateOpts.requireNonEmptyString(opts.name,
+    "ai.adverseDecision.wrap: opts.name is required",
+    AdverseDecisionError, "ai-adverse/bad-name");
+  validateOpts.requireNonEmptyString(opts.model,
+    "ai.adverseDecision.wrap: opts.model is required (model id + version for audit attribution)",
+    AdverseDecisionError, "ai-adverse/bad-model");
+  validateOpts.requireNonEmptyString(opts.legalBasis,
+    "ai.adverseDecision.wrap: opts.legalBasis is required (e.g. 'ecoa-1002.9' / 'gdpr-22' / 'colorado-ai-act')",
+    AdverseDecisionError, "ai-adverse/bad-legal-basis");
+  if (typeof opts.decide !== "function") {
+    throw new AdverseDecisionError("ai-adverse/bad-decide",
+      "ai.adverseDecision.wrap: opts.decide must be a function (subject) -> { outcome, principalReasons }");
+  }
+  var name = opts.name;
+  var model = opts.model;
+  var legalBasis = opts.legalBasis;
+  var decide = opts.decide;
+  var onAdverse = typeof opts.onAdverse === "function" ? opts.onAdverse : null;
+  var auditOn = opts.audit !== false;
+  var now = typeof opts.now === "function" ? opts.now : function () { return Date.now(); };
+
+  var deadlines = REGIME_DEADLINES[legalBasis] || REGIME_DEADLINES["operator-defined"];
+
+  function _emitAudit(action, outcome, metadata) {
+    if (!auditOn) return;
+    try {
+      audit().safeEmit({
+        action:   "ai.adverse_decision." + action,
+        outcome:  outcome,
+        metadata: metadata || {},
+      });
+    } catch (_e) { /* drop-silent */ }
+  }
+  function _emitMetric(verb, n, labels) {
+    try { observability().safeEvent("ai.adverse_decision." + verb, n || 1, labels || {}); }
+    catch (_e) { /* drop-silent */ }
+  }
+
+  return async function adverseDecisionDecorated(subject) {
+    if (!subject || typeof subject !== "object") {
+      throw new AdverseDecisionError("ai-adverse/bad-subject",
+        "ai.adverseDecision: subject must be an object with at least { id }");
+    }
+    var subjectId = subject.id || null;
+    var decidedAt = now();
+    var decision;
+    try {
+      decision = await decide(subject);
+    } catch (e) {
+      _emitAudit("decide_failed", "failure", { name: name, subjectId: subjectId, error: (e && e.message) || String(e) });
+      throw e;
+    }
+    if (!decision || typeof decision !== "object") {
+      throw new AdverseDecisionError("ai-adverse/bad-decision-shape",
+        "ai.adverseDecision: opts.decide must return an object with { outcome, principalReasons }");
+    }
+    var outcome = decision.outcome;
+    var isAdverse = outcome === "adverse" || outcome === "denied" || outcome === "rejected";
+
+    _emitAudit("decided", isAdverse ? "denied" : "success", {
+      name: name, model: model, legalBasis: legalBasis,
+      subjectId: subjectId, outcome: outcome,
+      principalReasons: Array.isArray(decision.principalReasons) ? decision.principalReasons : [],
+    });
+    _emitMetric("decided", 1, { name: name, outcome: outcome });
+
+    if (isAdverse) {
+      decision.adverseNotice = {
+        subjectId:        subjectId,
+        decisionAt:       decidedAt,
+        model:            model,
+        legalBasis:       legalBasis,
+        regulation:       deadlines.regulation,
+        principalReasons: Array.isArray(decision.principalReasons) ? decision.principalReasons : [],
+        consumerRights: {
+          requestExplanation: deadlines.explanation !== null,
+          requestHumanReview: deadlines.humanReview !== null,
+          requestAppeal:      deadlines.appeal !== null,
+          requestData:        true,
+          statutoryDeadlines: {
+            explanation: deadlines.explanation,
+            humanReview: deadlines.humanReview,
+            appeal:      deadlines.appeal,
+          },
+        },
+      };
+      if (onAdverse) {
+        try { await onAdverse(subject, decision); }
+        catch (e) { _emitAudit("on_adverse_threw", "failure", { error: (e && e.message) || String(e) }); }
+      }
+    }
+    return decision;
+  };
+}
+
+module.exports = {
+  wrap:                  wrap,
+  REGIME_DEADLINES:      REGIME_DEADLINES,
+  AdverseDecisionError:  AdverseDecisionError,
+  VALID_REGIMES:         Object.keys(REGIME_DEADLINES),
+};