xytara 2.6.0 → 2.8.0

package/RELEASE_NOTES.md

@@ -1,3 +1,26 @@
+# xytara 2.8.0 Release Notes
+
+`xytara` 2.8.0 is the release-boundary hardening line for live-provider promotion discipline, treasury/operator public-claim safety, and pricing experiment guardrails.
+
+Highlights:
+
+- adds framework-provider promotion evidence gates so LangGraph/LangChain style claims stay reference-contract until endpoint, auth, health, latency, failure, and proof-fact evidence exists
+- hardens pricing experiment planning and launch gates so optimization remains sample-maturity and operator-review gated
+- hardens treasury public claim boundaries so public surfaces do not leak landing/custody/provider refs or promote readiness-only/internal rails as live
+- hardens operator observability boundaries so read-only views cannot drift into mutation, settlement submission, fund movement, unsafe attention actions, or secret-bearing control behavior
+- keeps the 2.7.0 clean-consumer packaging and release-smoke posture intact while making expansion claims more defensible
+
+# xytara 2.7.0 Release Notes
+
+`xytara` 2.7.0 is the expansion-closeout release line for package-hardening, clean-consumer release smoke testing, and disciplined adapter/product claim boundaries.
+
+Highlights:
+
+- ships `scripts/` in the npm artifact so packaged verification commands are available to consumers
+- adds release-candidate guards that fail if required verifier scripts are missing from `npm pack`
+- participates in the Naxytra release-smoke harness that installs packed tarballs into a clean consumer project before synchronized release
+- keeps the 2.6.0 expansion capabilities and adapter surfaces intact while closing the packaging reliability gap
+
 # xytara 2.6.0 Release Notes
 
 `xytara` 2.6.0 is the expansion release line for first-run execution polish, provider-backed adapter depth, and framework reference adapters while preserving the existing machine-commerce, settlement, observability, and release surfaces.

package/index.js

@@ -35,6 +35,14 @@ const {
   buildAdapterPack,
   summarizeAdapterPack
 } = require("./lib/adapter_pack");
+const {
+  buildFrameworkProviderPromotionPack,
+  summarizeFrameworkProviderPromotionPack
+} = require("./lib/framework_provider_promotion");
+const {
+  buildPricingExperimentPlan,
+  summarizePricingExperimentPlan
+} = require("./lib/pricing_optimization_contract");
 const {
   buildPublishPlan,
   summarizePublishPlan
@@ -159,6 +167,10 @@ module.exports = {
   summarizeReleaseHistory,
   buildAdapterPack,
   summarizeAdapterPack,
+  buildFrameworkProviderPromotionPack,
+  summarizeFrameworkProviderPromotionPack,
+  buildPricingExperimentPlan,
+  summarizePricingExperimentPlan,
   buildPublishPlan,
   summarizePublishPlan,
   buildEcosystemEntryPack,

package/lib/framework_provider_promotion.js

@@ -0,0 +1,235 @@
+"use strict";
+
+const packageJson = require("../package.json");
+
+const FRAMEWORK_PROVIDER_CANDIDATES = Object.freeze([
+  Object.freeze({
+    framework_id: "langgraph",
+    adapter_id: "reference.framework.langgraph",
+    task_ref: "framework.langgraph.execute",
+    endpoint_env: "XYTARA_LANGGRAPH_PROVIDER_URL",
+    auth_env: "XYTARA_LANGGRAPH_PROVIDER_TOKEN",
+    health_path_env: "XYTARA_LANGGRAPH_PROVIDER_HEALTH_PATH"
+  }),
+  Object.freeze({
+    framework_id: "langchain",
+    adapter_id: "reference.framework.langchain",
+    task_ref: "framework.langchain.execute",
+    endpoint_env: "XYTARA_LANGCHAIN_PROVIDER_URL",
+    auth_env: "XYTARA_LANGCHAIN_PROVIDER_TOKEN",
+    health_path_env: "XYTARA_LANGCHAIN_PROVIDER_HEALTH_PATH"
+  })
+]);
+
+const FRAMEWORK_PROVIDER_PROMOTION_REQUIREMENTS = Object.freeze([
+  "endpoint_configured",
+  "auth_configured",
+  "health_check_passes",
+  "latency_observed",
+  "failure_behavior_bounded",
+  "proof_fact_shape_preserved",
+  "operator_evidence_recorded"
+]);
+
+const FRAMEWORK_PROVIDER_PROMOTION_REJECTION_CODES = Object.freeze([
+  "framework_not_registered",
+  "candidate_not_live_check_ready",
+  "adapter_id_mismatch",
+  "task_ref_mismatch",
+  "operator_evidence_missing",
+  "auth_boundary_evidence_missing",
+  "health_check_missing",
+  "health_check_failed",
+  "latency_measurement_missing",
+  "latency_budget_exceeded",
+  "failure_behavior_evidence_missing",
+  "proof_fact_shape_evidence_missing",
+  "secret_material_forbidden"
+]);
+
+function normalizeString(value) {
+  return typeof value === "string" ? value.trim() : "";
+}
+
+function containsSecretMaterial(value) {
+  if (!value || typeof value !== "object") return false;
+  const secretishKey = /(secret|token|credential|password|private[_-]?key|authorization)/i;
+  const secretishValue = /(bearer\s+[a-z0-9._-]{8,}|sk_live_|npm_[a-z0-9]|ghp_[a-z0-9]|xox[baprs]-)/i;
+  const stack = [value];
+  while (stack.length > 0) {
+    const current = stack.pop();
+    if (!current || typeof current !== "object") continue;
+    for (const [key, entry] of Object.entries(current)) {
+      if (secretishKey.test(String(key))) return true;
+      if (typeof entry === "string" && secretishValue.test(entry)) return true;
+      if (entry && typeof entry === "object") stack.push(entry);
+    }
+  }
+  return false;
+}
+
+function boolFromEnv(value) {
+  const normalized = normalizeString(value).toLowerCase();
+  return ["1", "true", "yes", "on"].includes(normalized);
+}
+
+function summarizeCandidate(candidate, env = process.env) {
+  const endpoint = normalizeString(env[candidate.endpoint_env]);
+  const authToken = normalizeString(env[candidate.auth_env]);
+  const healthPath = normalizeString(env[candidate.health_path_env]) || "/health";
+  const endpointConfigured = Boolean(endpoint);
+  const authConfigured = Boolean(authToken);
+  const liveCheckReady = endpointConfigured && authConfigured;
+  return {
+    framework_id: candidate.framework_id,
+    adapter_id: candidate.adapter_id,
+    task_ref: candidate.task_ref,
+    state: liveCheckReady ? "live_check_ready" : "reference_contract_only",
+    endpoint_configured: endpointConfigured,
+    auth_configured: authConfigured,
+    health_path: healthPath,
+    endpoint_env: candidate.endpoint_env,
+    auth_env: candidate.auth_env,
+    health_path_env: candidate.health_path_env,
+    promotion_evidence_template: {
+      framework_id: candidate.framework_id,
+      adapter_id: candidate.adapter_id,
+      task_ref: candidate.task_ref,
+      operator_evidence_ref: "ops.framework_provider.<framework_id>.<date>",
+      auth_boundary_ref: "ops.framework_provider.auth_boundary.<framework_id>.<date>",
+      health_check: {
+        status_code: 200,
+        health_ok: true
+      },
+      latency_ms: 250,
+      latency_budget_ms: 2000,
+      failure_behavior_ref: "ops.framework_provider.failure_behavior.<framework_id>.<date>",
+      proof_fact_shape_ref: "ops.framework_provider.proof_facts.<framework_id>.<date>"
+    },
+    required_live_evidence: [
+      "real_external_endpoint",
+      "auth_or_access_boundary",
+      "health_check_response",
+      "bounded_latency_measurement",
+      "failure_behavior_observed",
+      "proof_fact_shape_preserved"
+    ],
+    claim_boundary: liveCheckReady
+      ? "may_run_live_promotion_check_but_must_not_claim_provider_live_until_check_evidence_is_recorded"
+      : "reference_adapter_only_no_live_external_provider_claim"
+  };
+}
+
+function buildFrameworkProviderPromotionPack(options = {}) {
+  const env = options.env || process.env;
+  const candidates = FRAMEWORK_PROVIDER_CANDIDATES.map((candidate) => summarizeCandidate(candidate, env));
+  const liveReadyCandidates = candidates.filter((candidate) => candidate.state === "live_check_ready");
+  const requireLive = boolFromEnv(env.XYTARA_FRAMEWORK_PROMOTION_REQUIRE_LIVE);
+  return {
+    ok: true,
+    product: packageJson.name,
+    category: "machine-commerce-framework-provider-promotion-pack",
+    pack_version: "xytara-framework-provider-promotion-pack-v1",
+    posture: "reference_framework_adapters_promote_only_with_external_endpoint_evidence",
+    promotion_state: liveReadyCandidates.length > 0 ? "live_check_ready" : "no_live_provider_evidence_configured",
+    require_live: requireLive,
+    framework_candidate_count: candidates.length,
+    live_check_ready_count: liveReadyCandidates.length,
+    promoted_provider_count: 0,
+    candidates,
+    promotion_requirements: FRAMEWORK_PROVIDER_PROMOTION_REQUIREMENTS.slice(),
+    deterministic_rejection_codes: FRAMEWORK_PROVIDER_PROMOTION_REJECTION_CODES.slice(),
+    strict_boundaries: [
+      "reference_framework_adapters_do_not_equal_live_provider_integrations",
+      "do_not_claim_langgraph_or_langchain_live_provider_without_endpoint_auth_health_and_latency_evidence",
+      "failed_or_missing_live_checks_keep_frameworks_in_reference_contract_state",
+      "live_provider_promotion_does_not_change_adapter_claims_for_unchecked_frameworks"
+    ],
+    linked_surfaces: {
+      framework_lane_ref: "/v1/frameworks",
+      framework_provider_promotion_ref: "/v1/framework-provider-promotion",
+      framework_provider_promotion_summary_ref: "/v1/framework-provider-promotion/summary",
+      adapter_depth_ref: "/v1/adapter-depth/summary",
+      integrations_ref: "/v1/integrations"
+    }
+  };
+}
+
+function validateFrameworkProviderPromotionEvidence(pack, evidence) {
+  const promotionPack = pack || {};
+  const evidencePacket = evidence || {};
+  const candidates = Array.isArray(promotionPack.candidates) ? promotionPack.candidates : [];
+  const frameworkId = normalizeString(evidencePacket.framework_id);
+  const candidate = candidates.find((entry) => entry && entry.framework_id === frameworkId) || null;
+  const healthCheck = evidencePacket.health_check || null;
+  const latencyValue = evidencePacket.latency_ms;
+  const latencyMs = Number(latencyValue);
+  const latencyBudgetMs = Number(evidencePacket.latency_budget_ms || 2000);
+  const rejectionCodes = [];
+
+  if (!candidate) {
+    rejectionCodes.push("framework_not_registered");
+  } else {
+    if (candidate.state !== "live_check_ready" || !candidate.endpoint_configured || !candidate.auth_configured) {
+      rejectionCodes.push("candidate_not_live_check_ready");
+    }
+    if (normalizeString(evidencePacket.adapter_id) && normalizeString(evidencePacket.adapter_id) !== candidate.adapter_id) {
+      rejectionCodes.push("adapter_id_mismatch");
+    }
+    if (normalizeString(evidencePacket.task_ref) && normalizeString(evidencePacket.task_ref) !== candidate.task_ref) {
+      rejectionCodes.push("task_ref_mismatch");
+    }
+  }
+  if (!normalizeString(evidencePacket.operator_evidence_ref)) rejectionCodes.push("operator_evidence_missing");
+  if (!normalizeString(evidencePacket.auth_boundary_ref)) rejectionCodes.push("auth_boundary_evidence_missing");
+  if (!healthCheck || typeof healthCheck !== "object") {
+    rejectionCodes.push("health_check_missing");
+  } else if (healthCheck.health_ok !== true || Number(healthCheck.status_code || 0) < 200 || Number(healthCheck.status_code || 0) >= 300) {
+    rejectionCodes.push("health_check_failed");
+  }
+  if (latencyValue === null || latencyValue === undefined || latencyValue === "" || !Number.isFinite(latencyMs) || latencyMs < 0) {
+    rejectionCodes.push("latency_measurement_missing");
+  } else if (Number.isFinite(latencyBudgetMs) && latencyBudgetMs > 0 && latencyMs > latencyBudgetMs) {
+    rejectionCodes.push("latency_budget_exceeded");
+  }
+  if (!normalizeString(evidencePacket.failure_behavior_ref)) rejectionCodes.push("failure_behavior_evidence_missing");
+  if (!normalizeString(evidencePacket.proof_fact_shape_ref)) rejectionCodes.push("proof_fact_shape_evidence_missing");
+  if (containsSecretMaterial(evidencePacket)) rejectionCodes.push("secret_material_forbidden");
+
+  return {
+    validation_version: "xytara-framework-provider-promotion-evidence-validation-v1",
+    promotion_allowed: rejectionCodes.length === 0,
+    framework_id: frameworkId || null,
+    rejection_codes: Array.from(new Set(rejectionCodes)),
+    required_requirements: FRAMEWORK_PROVIDER_PROMOTION_REQUIREMENTS.slice(),
+    boundary: "framework_provider_promotion_requires_endpoint_auth_health_latency_failure_and_proof_fact_evidence_without_secret_material"
+  };
+}
+
+function summarizeFrameworkProviderPromotionPack(options = {}) {
+  const pack = buildFrameworkProviderPromotionPack(options);
+  return {
+    ok: true,
+    product: pack.product,
+    category: "machine-commerce-framework-provider-promotion-summary",
+    summary_version: "xytara-framework-provider-promotion-summary-v1",
+    posture: pack.posture,
+    promotion_state: pack.promotion_state,
+    require_live: pack.require_live,
+    framework_candidate_count: pack.framework_candidate_count,
+    live_check_ready_count: pack.live_check_ready_count,
+    promoted_provider_count: pack.promoted_provider_count,
+    promotion_requirement_count: pack.promotion_requirements.length,
+    deterministic_rejection_code_count: pack.deterministic_rejection_codes.length,
+    boundary_count: pack.strict_boundaries.length,
+    linked_surfaces: pack.linked_surfaces
+  };
+}
+
+module.exports = {
+  FRAMEWORK_PROVIDER_CANDIDATES,
+  FRAMEWORK_PROVIDER_PROMOTION_REJECTION_CODES,
+  buildFrameworkProviderPromotionPack,
+  summarizeFrameworkProviderPromotionPack,
+  validateFrameworkProviderPromotionEvidence
+};

package/lib/operator_intelligence.js

@@ -5,12 +5,71 @@ const { buildEconomicsIntelligenceSummary } = require("./commerce_economics");
 const { buildPartnerIntelligencePack } = require("./partner_intelligence");
 const { buildRevenueSignalSummary } = require("./pricing_optimization_contract");
 
+const OPERATOR_OBSERVABILITY_REJECTION_CODES = [
+  "boundary_missing",
+  "missing_linked_surface",
+  "mutation_surface_linked",
+  "settlement_submission_surface_linked",
+  "fund_movement_surface_linked",
+  "unsafe_attention_action",
+  "secret_material_forbidden",
+  "count_not_number"
+];
+
+const OPERATOR_OBSERVABILITY_REQUIRED_SURFACES = [
+  "activity_ledger_ref",
+  "payment_ledger_ref",
+  "reconciliation_report_ref",
+  "deliveries_ref",
+  "settlement_ref",
+  "adapter_depth_ref",
+  "pricing_revenue_signal_ref",
+  "operator_intelligence_ref"
+];
+
 function valuesFromCollection(collection) {
   if (!collection) return [];
   if (collection instanceof Map) return Array.from(collection.values());
   return Array.isArray(collection) ? collection : [];
 }
 
+function containsSecretMaterial(value) {
+  if (!value || typeof value !== "object") return false;
+  const secretishKey = /(secret|token|credential|password|private[_-]?key|authorization|api[_-]?key)/i;
+  const secretishValue = /(bearer\s+[a-z0-9._-]{8,}|sk_live_|npm_[a-z0-9]|ghp_[a-z0-9]|xox[baprs]-)/i;
+  const stack = [value];
+  while (stack.length > 0) {
+    const current = stack.pop();
+    if (!current || typeof current !== "object") continue;
+    for (const [key, entry] of Object.entries(current)) {
+      if (secretishKey.test(String(key))) return true;
+      if (typeof entry === "string" && secretishValue.test(entry)) return true;
+      if (entry && typeof entry === "object") stack.push(entry);
+    }
+  }
+  return false;
+}
+
+function isUnsafeLinkedSurface(value) {
+  const normalized = String(value || "").toLowerCase();
+  return /\/(submit|refund|grant|release|rotate|delete|mutate|write|webhook|checkout)(\/|$)|submission|fund-movement|fund_movement/.test(normalized);
+}
+
+function isSettlementSubmissionSurface(value) {
+  const normalized = String(value || "").toLowerCase();
+  return /settlement.*(submit|submission|broadcast|raw_tx)|\/submit(\/|$)/.test(normalized);
+}
+
+function isFundMovementSurface(value) {
+  const normalized = String(value || "").toLowerCase();
+  return /(fund|treasury|credit).*(release|transfer|withdraw|grant|refund|disburse)|external-credit-grants/.test(normalized);
+}
+
+function isUnsafeAttentionAction(action) {
+  const normalized = String(action || "").toLowerCase();
+  return /^(submit|grant|refund|release|rotate|delete|write|mutate|broadcast|withdraw|transfer|disburse)_/.test(normalized);
+}
+
 function unwrapTransaction(entry) {
   if (entry && entry.transaction) return entry.transaction;
   return entry || null;
@@ -269,10 +328,52 @@ function buildOperatorObservabilityPack(state, input) {
       pricing_revenue_signal_ref: "/v1/pricing-optimization/revenue-signal-summary",
       operator_intelligence_ref: "/v1/operator-intelligence"
     },
+    deterministic_rejection_codes: OPERATOR_OBSERVABILITY_REJECTION_CODES.slice(),
     boundary: "read_only_operator_visibility_no_fund_movement_no_settlement_submission_no_secret_material"
   };
 }
 
+function validateOperatorObservabilityBoundary(packInput) {
+  const pack = packInput || {};
+  const rejectionCodes = [];
+  const linkedSurfaces = pack.linked_surfaces || {};
+  const counts = pack.counts || {};
+  if (pack.boundary !== "read_only_operator_visibility_no_fund_movement_no_settlement_submission_no_secret_material") {
+    rejectionCodes.push("boundary_missing");
+  }
+  for (const surfaceName of OPERATOR_OBSERVABILITY_REQUIRED_SURFACES) {
+    if (!linkedSurfaces[surfaceName]) {
+      rejectionCodes.push("missing_linked_surface");
+    }
+  }
+  for (const surfaceRef of Object.values(linkedSurfaces)) {
+    if (isUnsafeLinkedSurface(surfaceRef)) rejectionCodes.push("mutation_surface_linked");
+    if (isSettlementSubmissionSurface(surfaceRef)) rejectionCodes.push("settlement_submission_surface_linked");
+    if (isFundMovementSurface(surfaceRef)) rejectionCodes.push("fund_movement_surface_linked");
+  }
+  const attentionQueue = Array.isArray(pack.attention_queue) ? pack.attention_queue : [];
+  for (const item of attentionQueue) {
+    if (item && isUnsafeAttentionAction(item.action)) {
+      rejectionCodes.push("unsafe_attention_action");
+    }
+  }
+  for (const [key, value] of Object.entries(counts)) {
+    if (key.endsWith("_count") && typeof value !== "number") {
+      rejectionCodes.push("count_not_number");
+    }
+  }
+  if (containsSecretMaterial(pack)) {
+    rejectionCodes.push("secret_material_forbidden");
+  }
+  return {
+    validation_version: "xytara-operator-observability-boundary-validation-v1",
+    observability_boundary_valid: rejectionCodes.length === 0,
+    rejection_codes: Array.from(new Set(rejectionCodes)),
+    deterministic_rejection_codes: OPERATOR_OBSERVABILITY_REJECTION_CODES.slice(),
+    boundary: "operator_observability_must_remain_read_only_without_secret_material_mutation_links_or_fund_movement_actions"
+  };
+}
+
 function summarizeOperatorObservabilityPack(state, input) {
   const pack = buildOperatorObservabilityPack(state, input);
   return {
@@ -292,6 +393,7 @@ function summarizeOperatorObservabilityPack(state, input) {
     adapter_failure_count: pack.counts.adapter_failure_count,
     pricing_sample_maturity: pack.pricing_telemetry_summary.sample_maturity,
     attention_item_count: pack.attention_queue.length,
+    deterministic_rejection_code_count: pack.deterministic_rejection_codes.length,
     linked_surfaces: pack.linked_surfaces
   };
 }
@@ -300,5 +402,6 @@ module.exports = {
   buildOperatorIntelligencePack,
   summarizeOperatorIntelligencePack,
   buildOperatorObservabilityPack,
-  summarizeOperatorObservabilityPack
+  summarizeOperatorObservabilityPack,
+  validateOperatorObservabilityBoundary
 };